propraven-com Account API

openapi: 3.2.0
info:
  title: PropRaven Account 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: Account
  description: Account-scoped usage, quota, and key-level reporting.
paths:
  /api/v1/account/usage:
    get:
      operationId: getAccountUsage
      summary: Current-period usage and quota
      description: Returns the calling key's current-period API usage, included allotment, remaining calls, configured per-minute and per-day rate limits, and the hard-cap status. Per-user (all of a user's API keys roll up to the same monthly counter, since they share a Stripe subscription). `lookups` reports the account's monthly lookup cap (record views and people data), a separate counter from API calls.
      tags:
      - Account
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Usage report.
          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'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
      x-sdk-group: account
      x-sdk-method: usage
components:
  headers:
    X-RateLimit-Reset:
      description: Unix timestamp (seconds) when the window described by X-RateLimit-Limit resets.
      schema:
        type: integer
        example: 1711670400
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 5
    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:
    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'
    RateLimitExceeded:
      description: Rate limit exceeded.
      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'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        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/rate-limit-exceeded
            title: Rate limit exceeded
            status: 429
            detail: Rate limit exceeded
            code: rate_limit_exceeded
  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
    AccountUsage:
      type: object
      required:
      - tier
      - period
      - period_start
      - period_end
      - calls_used
      - calls_included
      - calls_remaining
      - rate_limit
      - hard_cap_enabled
      - auth_source
      properties:
        tier:
          type: string
          enum:
          - free
          - starter
          - pro
          - scale
          - api_100k
        period:
          type: string
        period_start:
          type: string
        period_end:
          type: string
        calls_used:
          type: integer
        calls_included:
          type: integer
          description: Plan allotment for the current period.
        calls_remaining:
          type: integer
        rate_limit:
          type: object
          required:
          - per_minute
          - per_day
          properties:
            per_minute:
              type: number
            per_day:
              type: number
        hard_cap_enabled:
          type: boolean
        auth_source:
          type: string
        hard_capped:
          type: boolean
          description: Whether further calls will be hard-rejected vs allowed-and-billed.
        lookups:
          type:
          - object
          - 'null'
          description: 'The account''s monthly LOOKUP cap — a separate counter from API calls. A record view and each people-data response (owner card, /owner, permits carrying owner/applicant names or contacts, tax-delinquency records, person licensees) spends one lookup for an account without a paid entitlement; a paid plan includes them. `limit: null` = unlimited. Null when the counter could not be read (never reported as 0).'
          required:
          - used
          - limit
          - remaining
          - plan
          properties:
            used:
              type: integer
            limit:
              type:
              - integer
              - 'null'
            remaining:
              type:
              - integer
              - 'null'
            plan:
              type: string
      additionalProperties: false
  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