Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: PropRaven Watch 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: Watch
paths:
/api/v1/watch:
get:
operationId: listWatches
summary: List your watches
description: List active watches for the X-CREDIT-TOKEN. Free.
tags:
- Watch
parameters:
- name: X-CREDIT-TOKEN
in: header
required: true
schema:
type: string
description: The pzc_ credit token (identity + wallet).
responses:
'200':
description: Your watches.
content:
application/json:
schema:
type: object
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'
'401':
description: Missing/invalid credit token.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'400':
$ref: '#/components/responses/BadRequest'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'500':
$ref: '#/components/responses/InternalError'
x-sdk-group: watch
x-sdk-method: list
post:
operationId: createWatch
summary: Create a watch (free)
description: 'Create a watch tied to your credit token: a filter over parcels/geography + change event types. It reports changes going FORWARD; poll it to receive (and pay per delta for) new changes. Managing watches is free. Body: { filter, event_types?, name? } where filter is { parcel_ids:[...] } | { canonical_ids:[...] } | { state_fips } | { county_fips, state_fips } and event_types is a subset of parcel.sold / parcel.owner_changed / parcel.permit_filed (default all). Parcel ids (1–500) are canonical `state_fips:county_fips:parcel_id` ids, parcel UUIDs, or bare parcel_ids that name exactly ONE served parcel; a bare id that names several parcels is refused (422, candidates listed). The watch is stored and matched on canonical ids; `parcel_resolution` reports how each input resolved.'
tags:
- Watch
parameters:
- name: X-CREDIT-TOKEN
in: header
required: true
schema:
type: string
description: The pzc_ credit token.
responses:
'200':
description: Watch created.
content:
application/json:
schema:
type: object
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'
'400':
description: Invalid filter/event_types.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
description: Missing/invalid credit token.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'422':
description: 'One or more parcel ids do not name exactly one parcel (problem+json, `code: parcel_identity_unresolved`, `issues[]` with per-input reason codes and candidate canonical ids). Nothing was created.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'500':
$ref: '#/components/responses/InternalError'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- filter
additionalProperties: false
properties:
name:
type: string
maxLength: 120
event_types:
type: array
minItems: 1
items:
type: string
enum:
- parcel.sold
- parcel.owner_changed
- parcel.permit_filed
description: 'Default: all three.'
filter:
type: object
description: 'Exactly one shape: `{parcel_ids: [...]}` / `{canonical_ids: [...]}` (1-500 ids), `{state_fips}` or `{state_fips, county_fips}`.'
properties:
parcel_ids:
type: array
items:
type: string
maxItems: 500
canonical_ids:
type: array
items:
type: string
maxItems: 500
state_fips:
type: string
county_fips:
type: string
x-sdk-group: watch
x-sdk-method: create
/api/v1/watch/{id}:
get:
operationId: pollWatch
summary: Poll a watch for new changes (priced per delta)
description: 'Poll new parcel_deeds / parcel_permits changes matching the watch since its per-source cursor. preview=true returns the pending count + exact price + a masked sample (FREE, no cursor move). A paid poll debits the credit balance PER DELTA (clamp($0.05 x event-strength, $0.02, $0.20), capped $20/poll), advances the cursor, and returns the full deltas. A poll with no new changes is free. Insufficient balance -> 402. Parcel watches match on the full parcel identity; each delta carries `canonical_id` + `match_basis`. A watch created before 2026-09-22 whose stored bare ids are ambiguous reports them in `identity_issues` (not matched) on every poll. Deed parties (grantor / grantee names and addresses, prior / new owner) are people data, delivered to accounts only: a poll paid with a credit token and no account (no API key, no signed-in session) receives the deltas with those fields set to null and a top-level `people_fields` marker (see PeopleFieldsWithheld). The events themselves (what changed, where, when, for how much) are unchanged.'
tags:
- Watch
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The watch id (wat_...).
- name: preview
in: query
required: false
schema:
type: boolean
description: FREE count + price + masked sample; no cursor move.
- name: limit
in: query
required: false
schema:
type: integer
description: Max deltas per source (default 50, max 200).
- name: X-CREDIT-TOKEN
in: header
required: true
schema:
type: string
description: The pzc_ credit token.
responses:
'200':
description: Deltas delivered (paid), a free preview, or a free empty poll.
content:
application/json:
schema:
type: object
properties:
deltas:
type: array
items:
type: object
people_fields:
$ref: '#/components/schemas/PeopleFieldsWithheld'
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: Insufficient credit balance for the pending deltas; top up and re-poll.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
description: Missing/invalid credit token.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'404':
description: Watch not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'400':
$ref: '#/components/responses/BadRequest'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'500':
$ref: '#/components/responses/InternalError'
x-sdk-group: watch
x-sdk-method: poll
delete:
operationId: deleteWatch
summary: Delete a watch
description: Deactivate a watch. Free.
tags:
- Watch
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The watch id.
- name: X-CREDIT-TOKEN
in: header
required: true
schema:
type: string
description: The pzc_ credit token.
responses:
'200':
description: Deleted.
content:
application/json:
schema:
type: object
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'
'404':
description: Watch not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'400':
$ref: '#/components/responses/BadRequest'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'500':
$ref: '#/components/responses/InternalError'
'401':
$ref: '#/components/responses/Unauthorized'
x-sdk-group: watch
x-sdk-method: delete
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
responses:
BadRequest:
description: A query or body parameter is invalid. Nothing was read or charged.
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'
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/invalid-parameter
title: Bad Request
status: 400
detail: 'limit: must be >= 1'
code: invalid_parameter
errors:
- param: limit
message: must be >= 1
Unauthorized:
description: Missing, malformed or invalid credential.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://api.propraven.com/errors/authentication-required
title: Unauthorized
status: 401
detail: Provide an API key in the Authorization header ('Bearer pz_...') or sign in via the web dashboard.
code: authentication_required
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
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'
schemas:
PeopleFieldsWithheld:
type: object
description: 'Additive marker on a record (or list) whose people fields were withheld because the caller has no PropRaven account. People fields are owner names, owner mailing / owner-address columns, entity principals, recorded-document party names and addresses (grantor/grantee, buyer/seller, prior/new owner), permit applicant names and the resolved `owner_contact` block. Withheld keys are kept and set to null (lists of people records become []), so the record''s shape does not change. Send an API key (`Authorization: Bearer pz_...`) or call from a signed-in session; on the paid products a settled x402 payment or a prepaid credit debit also delivers people data.'
required:
- status
- code
- reason
- note
properties:
status:
type: string
enum:
- withheld
code:
type: string
enum:
- account_required
reason:
type: string
enum:
- people_data_requires_account
note:
type: string
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
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