propraven-com Distribution API

openapi: 3.2.0
info:
  title: PropRaven Distribution 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: Distribution
  description: Bulk delivery metadata (Cloudflare R2, Databricks Delta Sharing). Signed-in session only; an anonymous call gets 401.
paths:
  /api/v1/r2-credentials:
    get:
      operationId: getR2DeliveryInfo
      summary: R2 delivery metadata
      description: 'Returns the R2 bucket, the prefixes a credential may name, the credential TTL limits in seconds, the catalog object and whether the caller''s plan carries R2 delivery. AUTHENTICATED (signed-in session only): an anonymous call gets HTTP 401 from the session gate and an API key is not accepted. Credentials themselves are minted with POST on the same path from a signed-in session (see https://propraven.com/docs/r2); that operation is not part of the API-key contract.'
      tags:
      - Distribution
      security:
      - sessionCookie: []
      responses:
        '200':
          description: R2 delivery metadata.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - bucket
                - endpoint_template
                - region
                - available_prefixes
                - max_ttl_seconds
                - default_ttl_seconds
                - docs
                - catalog
                - entitled
                - upgrade_url
                properties:
                  bucket:
                    type: string
                    example: propraven-data
                  endpoint_template:
                    type: string
                    example: https://<account_id>.r2.cloudflarestorage.com
                  region:
                    type: string
                    example: auto
                  available_prefixes:
                    type: array
                    items:
                      type: string
                    example:
                    - parcels-silver/
                    - parcels-wide/
                    - permits/
                    - _catalog.json
                  max_ttl_seconds:
                    type: integer
                    example: 43200
                  default_ttl_seconds:
                    type: integer
                    example: 43200
                  docs:
                    type: string
                    example: https://propraven.com/docs/r2
                  catalog:
                    type: object
                    additionalProperties: false
                    required:
                    - uri
                    - prefix
                    properties:
                      uri:
                        type: string
                        example: s3://propraven-data/_catalog.json
                      prefix:
                        type: string
                        example: _catalog.json
                  entitled:
                    type:
                    - boolean
                    - 'null'
                    description: Whether the caller's plan carries R2 delivery; null when the plan lookup failed.
                  upgrade_url:
                    type: string
                    example: https://propraven.com/subscribe
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
      x-sdk-group: distribution
      x-sdk-method: r2Info
  /api/v1/data/databricks/grant:
    get:
      operationId: getDatabricksShareInfo
      summary: Databricks Delta Sharing metadata
      description: 'Returns the Delta Share name, the recipient types, whether delivery is configured and whether the channel is paused, with the channel status and its date. AUTHENTICATED (signed-in session only): an anonymous call gets HTTP 401 from the session gate and an API key is not accepted. Provisioning is POST on the same path from a signed-in session (see https://propraven.com/docs/databricks); while the channel is paused it returns 503 with a waitlist message. That operation is not part of the API-key contract.'
      tags:
      - Distribution
      security:
      - sessionCookie: []
      responses:
        '200':
          description: Databricks delivery metadata.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - share
                - protocol
                - recipient_types
                - configured
                - paused
                - status
                - status_as_of
                - docs
                properties:
                  share:
                    type: string
                    example: propraven_silver
                  protocol:
                    type: string
                    example: delta-sharing
                  recipient_types:
                    type: array
                    items:
                      type: string
                      enum:
                      - DATABRICKS
                      - TOKEN
                  configured:
                    type: boolean
                  paused:
                    type: boolean
                    description: True while DATABRICKS_CHANNEL_PAUSED is set; POST then returns 503.
                  status:
                    type: string
                    enum:
                    - paused
                    - live
                    description: The published channel status (the same text /docs/databricks shows).
                  status_as_of:
                    type: string
                    format: date
                    example: '2026-10-15'
                  docs:
                    type: string
                    example: https://propraven.com/docs/databricks
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
      x-sdk-group: distribution
      x-sdk-method: databricksInfo
components:
  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
    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'
    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'
  headers:
    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
  schemas:
    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