propraven-com Storefront API

openapi: 3.2.0
info:
  title: PropRaven Storefront API
  version: 1.2.1
  description: 'National property intelligence API: US parcels with ownership, valuation, permit, deed, risk and market data.


    **Base URL.** `https://propraven.com/api/v1` (every path below starts with `/api/v1`; `https://api.propraven.com/api/v1` serves the same API). The REST API is for server-side use: it sends no CORS headers, and API keys are secret.


    **Authentication.** `Authorization: Bearer pz_…`. Create a key in the dashboard. A few endpoints are key-optional (marked with an empty security requirement); anonymous calls to them are limited to 100 a day and 60 a minute per IP. The Free plan includes 1,000 API calls a month (60 a minute, 1,000 a day); `GET /api/v1/account/usage` reports your plan, period usage and limits.


    **Numbers.** Since API 1.2.0, every field this spec types as `number` or `integer` is a JSON number. (Before 1.2.0, values read from Postgres `numeric` and `bigint` columns, such as `total_assessed_value`, were sent as strings like "19388200.00".) Identifiers stay strings: `parcel_id`, `apn`, `county_fips`, `state_fips`, `zip`.


    **Errors.** Every error is an RFC 7807 problem (`application/problem+json`, schema `Problem`) with a stable `code`. Bad parameters are a 400 `invalid_parameter` naming each one in `errors`; an unknown endpoint is a 404 `not_found`; an unsupported method is a 405 with an `Allow` header; a query that runs out of time is a 504 `query_timeout` with `Retry-After`. Error bodies never contain database text. Paid endpoints answer an unpaid call with an x402 `402 Payment Required` envelope (`x402Version`, `accepts`).


    **Pagination.** List endpoints take `limit` and `offset` and return `{data, total, limit, offset}`; request the next page with `offset + limit` until a page is shorter than `limit` or `offset` reaches `total`. `GET /api/v1/search/full` uses a keyset cursor: pass the previous page''s `nextCursor` as `after` until `nextCursor` is null.


    **Rate limits.** Burst and daily windows by plan: Free 60 a minute / 1,000 a day; Developer 3,000 a minute / 100,000 a day; Team 12,000 a minute / 1,000,000 a day; key-optional endpoints called without a key, 60 a minute / 100 a day per IP. Authenticated responses carry `X-RateLimit-Limit` / `-Remaining` / `-Reset` (Unix seconds), all describing the window that will refuse you first. Every 429 and every 503 carries `Retry-After` (seconds): wait at least that long, then retry with backoff. A **429** means your plan''s window is used up (`rate_limit_exceeded`); or the key is cooling down for up to 15 minutes because its request rate spiked far above its own recent baseline (`key_cooldown`; it is not banned or revoked, and your other keys are unaffected); or one address failed authentication more than 60 times in a minute (`auth_failures_exceeded`). A **503** means PropRaven is briefly shedding load to protect the service (`load_shed`; calls without a key first, paid plans last) or the rate limiter is briefly unavailable. The MCP endpoint (`/mcp`) answers the same cases with the same status and `Retry-After`, plus a JSON-RPC error with code -32003.


    **SDKs.** Official clients generated from this spec: `@propraven/sdk` (npm), `propraven` (PyPI) and `github.com/jdw2111/propraven-go`. Each retries 429/503/504 with backoff, raises typed errors on the `Problem` shape, paginates, and verifies webhook signatures. The `x-sdk-group`, `x-sdk-method` and `x-sdk-pagination` extensions name each operation in the SDKs.'
  contact:
    name: PropRaven Support
    url: https://propraven.com/docs
    email: support@propraven.com
  license:
    name: Commercial
    url: https://propraven.com/terms#data-license
servers:
- url: https://propraven.com
  description: Production. Every path starts with /api/v1. (https://api.propraven.com serves the same API.)
security:
- bearerAuth: []
tags:


# --- truncated at 32 KB (79 KB total) ---
# Full source: https://artifacts.apis.io/propraven-com/openapi/propraven-com-storefront-api-openapi.yml