Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: PropRaven Verify 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:
- name: Verify
paths:
/api/v1/verify:
post:
operationId: verifyFactsBatch
summary: Verify facts (batch, paid per lookup) - FREE preview
description: 'Verify catalogued FACTS: one (parcel, field) assertion per lookup, batch (POST body { lookups: [{ parcel_id, fields }] }, up to 1000 parcels) or single (GET ?parcel_id&fields). Priced per lookup, bulk-discounted ($0.02/$0.012/$0.006), capped $20. Pay from a prepaid credit balance (X-CREDIT-TOKEN) or per call via x402. preview=true returns count+price free; empty/all-invalid is free. Fields whitelisted (is_sfha, flood_zone, nri_risk_score, owner_occupied, is_absentee, owner_name, assessed_value, market_value, building_sqft, year_built, property_type, zoning, lot_size_acres, last_sale_date/price, address/city/state/zip); unknown parcel -> found:false. `owner_name` is people data: it is verified for an account (API key or signed-in session), or for a caller without one once its x402 payment settles or its credit debit succeeds. An UNPAID caller without an account (no X-PAYMENT / X-CREDIT-TOKEN, or preview=true) that asks for owner_name is refused with HTTP 401 `code: "account_required"` before the quote; every other field is unaffected.'
tags:
- Verify
parameters:
- name: preview
in: query
required: false
schema:
type: string
description: FREE count + price.
- name: X-CREDIT-TOKEN
in: header
required: false
schema:
type: string
description: Prepaid credit token to debit the batch.
- name: X-PAYMENT
in: header
required: false
schema:
type: string
description: Base64 x402 PaymentPayload.
responses:
'200':
description: Verified facts, a free preview, or a free empty result.
content:
application/json:
schema:
type: object
required:
- lookup_count
- parcel_count
- quote
- provenance
- preview
- note
properties:
lookup_count:
type: integer
parcel_count:
type: integer
quote:
type: object
required:
- per_lookup
- total
- total_usd
- total_atomic_usdc
- asset
- lookup_count
- breakdown
- pay
- note
properties:
per_lookup:
type: object
required:
- amount
- currency
properties:
amount:
type: string
currency:
type: string
total:
type: object
required:
- amount
- currency
properties:
amount:
type: string
currency:
type: string
total_usd:
type: number
total_atomic_usdc:
type: string
asset:
type: string
lookup_count:
type: integer
breakdown:
type: object
required:
- per_lookup_usd
- total_raw
- capped
properties:
per_lookup_usd:
type: number
total_raw:
type: number
capped:
type: boolean
pay:
type: array
items:
type:
- string
- 'null'
note:
type: string
provenance:
type: object
required:
- source
- source_datasets
- as_of
- as_of_basis
- serving_epoch
- freshness_status
- catalog_reference
- note
properties:
source:
type: string
source_datasets:
type: array
items:
type:
- string
- 'null'
as_of:
type:
- string
- 'null'
as_of_basis:
type:
- string
- 'null'
serving_epoch:
type:
- string
- 'null'
freshness_status:
type: string
catalog_reference:
type: object
required:
- catalog_version
- catalog_generated_at
- catalog_seal
properties:
catalog_version:
type: string
catalog_generated_at:
type: string
catalog_seal:
type: object
required:
- algorithm
- value
- covers
properties:
algorithm:
type: string
value:
type: string
covers:
type: string
note:
type: string
preview:
type: boolean
note:
type: string
additionalProperties: false
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
'402':
description: Payment required — accepts[0].maxAmountRequired carries the batch price (USDC atomic units).
content:
application/json:
schema:
$ref: '#/components/schemas/X402PaymentRequired'
'400':
description: No valid lookups.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
description: '`owner_name` requested without an account and without a payment, or on the free preview (`code: "account_required"`, `reason: "people_data_requires_account"`).'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://api.propraven.com/errors/account-required
title: Account required
status: 401
detail: Owner names, owner mailing addresses and other people data require a PropRaven account.
code: account_required
reason: people_data_requires_account
'405':
$ref: '#/components/responses/MethodNotAllowed'
'500':
$ref: '#/components/responses/InternalError'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- lookups
additionalProperties: false
properties:
lookups:
type: array
minItems: 1
maxItems: 1000
items:
type: object
required:
- parcel_id
- fields
additionalProperties: false
properties:
parcel_id:
type: string
example: 37:119:12104406
fields:
type: array
minItems: 1
items:
type: string
example:
- is_sfha
- year_built
x-sdk-group: verify
x-sdk-method: batch
get:
operationId: verifyFactsSingle
summary: Verify facts for one parcel
description: 'Verify catalogued FACTS: one (parcel, field) assertion per lookup, batch (POST body { lookups: [{ parcel_id, fields }] }, up to 1000 parcels) or single (GET ?parcel_id&fields). Priced per lookup, bulk-discounted ($0.02/$0.012/$0.006), capped $20. Pay from a prepaid credit balance (X-CREDIT-TOKEN) or per call via x402. preview=true returns count+price free; empty/all-invalid is free. Fields whitelisted (is_sfha, flood_zone, nri_risk_score, owner_occupied, is_absentee, owner_name, assessed_value, market_value, building_sqft, year_built, property_type, zoning, lot_size_acres, last_sale_date/price, address/city/state/zip); unknown parcel -> found:false. `owner_name` is people data: it is verified for an account (API key or signed-in session), or for a caller without one once its x402 payment settles or its credit debit succeeds. An UNPAID caller without an account (no X-PAYMENT / X-CREDIT-TOKEN, or preview=true) that asks for owner_name is refused with HTTP 401 `code: "account_required"` before the quote; every other field is unaffected.'
tags:
- Verify
parameters:
- name: parcel_id
in: query
required: true
schema:
type: string
example: 37:119:12104406
description: Canonical state:county:parcel.
- name: fields
in: query
required: true
schema:
type: string
example: is_sfha,owner_occupied
description: Comma-separated field aliases.
- name: preview
in: query
required: false
schema:
type: string
description: FREE count + price.
- name: X-CREDIT-TOKEN
in: header
required: false
schema:
type: string
description: Prepaid credit token.
- name: X-PAYMENT
in: header
required: false
schema:
type: string
description: Base64 x402 PaymentPayload.
responses:
'200':
description: Verified facts / preview / empty.
content:
application/json:
schema:
type: object
required:
- lookup_count
- parcel_count
- quote
- provenance
- preview
- note
properties:
lookup_count:
type: integer
parcel_count:
type: integer
quote:
type: object
required:
- per_lookup
- total
- total_usd
- total_atomic_usdc
- asset
- lookup_count
- breakdown
- pay
- note
properties:
per_lookup:
type: object
required:
- amount
- currency
properties:
amount:
type: string
currency:
type: string
total:
type: object
required:
- amount
- currency
properties:
amount:
type: string
currency:
type: string
total_usd:
type: number
total_atomic_usdc:
type: string
asset:
type: string
lookup_count:
type: integer
breakdown:
type: object
required:
- per_lookup_usd
- total_raw
- capped
properties:
per_lookup_usd:
type: number
total_raw:
type: number
capped:
type: boolean
pay:
type: array
items:
type:
- string
- 'null'
note:
type: string
provenance:
type: object
required:
- source
- source_datasets
- as_of
- as_of_basis
- serving_epoch
- freshness_status
- catalog_reference
- note
properties:
source:
type: string
source_datasets:
type: array
items:
type:
- string
- 'null'
as_of:
type:
- string
- 'null'
as_of_basis:
type:
- string
- 'null'
serving_epoch:
type:
- string
- 'null'
freshness_status:
type: string
catalog_reference:
type: object
required:
- catalog_version
- catalog_generated_at
- catalog_seal
properties:
catalog_version:
type: string
catalog_generated_at:
type: string
catalog_seal:
type: object
required:
- algorithm
- value
- covers
properties:
algorithm:
type: string
value:
type: string
covers:
type: string
note:
type: string
preview:
type: boolean
note:
type: string
additionalProperties: false
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
'402':
description: Payment required — accepts[0].maxAmountRequired carries the batch price (USDC atomic units).
content:
application/json:
schema:
$ref: '#/components/schemas/X402PaymentRequired'
'400':
description: Missing parcel_id/fields.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
description: '`owner_name` requested without an account and without a payment, or on the free preview (`code: "account_required"`, `reason: "people_data_requires_account"`).'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://api.propraven.com/errors/account-required
title: Account required
status: 401
detail: Owner names, owner mailing addresses and other people data require a PropRaven account.
code: account_required
reason: people_data_requires_account
'405':
$ref: '#/components/responses/MethodNotAllowed'
'500':
$ref: '#/components/responses/InternalError'
x-sdk-group: verify
x-sdk-method: get
components:
headers:
X-RateLimit-Reset:
description: Unix timestamp (seconds) when the window described by X-RateLimit-Limit resets.
schema:
type: integer
example: 1711670400
X-RateLimit-Remaining:
description: Calls left in the window described by X-RateLimit-Limit.
schema:
type: integer
example: 997
X-Request-Id:
description: Support handle for this request; equals the problem body's `request_id`. Sent on every error response, including 401.
schema:
type: string
X-RateLimit-Limit:
description: Size of the rate-limit window that will refuse you first — the per-minute burst window or the per-day window, whichever has fewer calls left. Limit, Remaining and Reset always describe that same window. Sent on every authenticated response (and on anonymous responses of key-optional endpoints).
schema:
type: integer
example: 1000
schemas:
X402PaymentRequired:
type: object
description: 'x402 (HTTP 402) payment-required body (x402 protocol v1). `accepts` lists the payment requirements a wallet-bearing agent signs to pay per call. Returned by both paid products: the per-parcel dossier (GET /api/v1/parcels/{id}/report) and the per-lead feed (GET /api/v1/leads/find). Flow: sign an EIP-3009 transferWithAuthorization for accepts[0].maxAmountRequired, base64 the PaymentPayload into the `X-PAYMENT` request header, and retry. The response also carries `Link: <https://propraven.com/terms#data-license>; rel="license"`, the data license that governs what the payment buys.'
properties:
x402Version:
type: integer
example: 1
description: x402 protocol version advertised (1 = the base exact scheme with maxAmountRequired).
error:
type: string
description: Human-readable reason payment is required or was rejected.
accepts:
type: array
description: 'The payment requirements to satisfy (one entry: the dossier, or the lead pull).'
items:
type: object
properties:
scheme:
type: string
example: exact
network:
type: string
example: base-sepolia
description: base-sepolia (testnet default) or base (mainnet).
maxAmountRequired:
type: string
example: '5000000'
description: 'The DYNAMIC price in the asset''s atomic units (USDC, 6 decimals). Dossier: clamp($5 x V x R x F, $2, $20) per parcel. Lead feed: min(count x clamp($0.25 x S x V, $0.05, $1.00), $20) per pull. 2000000 = $2.00, 6250000 = $6.25, 20000000 = the $20 cap. Sign for exactly this amount.'
resource:
type: string
description: The absolute URL being paid for.
description:
type: string
mimeType:
type: string
example: application/json
payTo:
type: string
description: Receiving wallet address.
maxTimeoutSeconds:
type: integer
description: How long the quote is valid before the client must re-fetch it.
asset:
type: string
description: ERC-20 asset contract address (USDC on the given network).
extra:
type: object
description: 'The asset''s EIP-712 domain { name, version } (USDC = { name: ''USDC'', version: ''2'' }) -- required by the exact EVM scheme so the facilitator can reconstruct the domain separator and verify the transferWithAuthorization signature.'
properties:
name:
type: string
example: USDC
version:
type: string
example: '2'
Problem:
type: object
description: 'THE error body of every /api/v1 endpoint (RFC 7807 problem details, served as `application/problem+json`). `code` is the stable machine-readable identifier (e.g. invalid_parameter, authentication_required, account_required, monthly_cap_reached, query_timeout, not_found, method_not_allowed); `detail` is human-readable and never contains database or driver text. Validation failures add `errors: [{param, message}]`. `request_id` identifies the request for support; every error response carries it, and the same value in the `X-Request-Id` header. Per-code members (e.g. `reason`, `retry_after`, `used` / `limit` / `plan` / `upgrade`, `allow`) sit beside the core members. Exception: an x402 `402 Payment Required` keeps the x402 protocol envelope (`x402Version`, `accepts`).'
required:
- type
- title
- status
- detail
- code
properties:
type:
type: string
title:
type: string
status:
type: integer
detail:
type: string
code:
type: string
description: Stable machine-readable code.
example: invalid_parameter
reason:
type: string
description: Finer reason for `code`, e.g. people_data_requires_account.
errors:
type: array
description: Per-parameter validation failures (400 invalid_parameter).
items:
type: object
required:
- param
- message
properties:
param:
type: string
example: limit
message:
type: string
example: must be >= 1
request_id:
type: string
description: Support handle for this request.
additionalProperties: true
example:
type: https://api.propraven.com/errors/invalid-parameter
title: Bad Request
status: 400
detail: 'limit: must be >= 1'
code: invalid_parameter
errors:
- param: limit
message: must be >= 1
request_id: iad1::abc123
responses:
MethodNotAllowed:
description: The endpoint exists but does not support this method. `Allow` lists the methods it does.
headers:
Allow:
description: Methods this endpoint supports.
schema:
type: string
example: GET, HEAD, OPTIONS
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://api.propraven.com/errors/method-not-allowed
title: Method Not Allowed
status: 405
detail: 'DELETE is not supported on /api/v1/parcels/[id]. Allowed: GET, HEAD, OPTIONS.'
code: method_not_allowed
allow:
- GET
- HEAD
- OPTIONS
InternalError:
description: Unexpected server error. The body never carries database or driver text.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://api.propraven.com/errors/internal-error
title: Internal Server Error
status: 500
detail: An internal error occurred.
code: internal_error
request_id: iad1::abc123
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: pz_*
description: 'API key with pz_ prefix. Pass as: Authorization: Bearer pz_your_api_key'
sessionCookie:
type: apiKey
in: cookie
name: sb-<project-ref>-auth-token
description: The signed-in web session (Supabase auth cookie) set by signing in at https://propraven.com/sign-in. Used only by account-scoped dashboard routes; an API key is not accepted on those routes.
externalDocs:
description: 'Connect your agent to PropRaven: the MCP server, the discover -> preview -> pay (x402) flow, and pricing.'
url: https://propraven.com/docs/agents