propraven-com Credits API

openapi: 3.2.0
info:
  title: PropRaven Credits 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: Credits
paths:
  /api/v1/storefront/credits/topup:
    get:
      operationId: fundCredits
      summary: Fund a prepaid credit balance over x402
      description: Pay `amount` USDC once via x402 to fund a prepaid credit balance; receive a credit token (pzc_...) to spend on any paid endpoint via the X-CREDIT-TOKEN header — the recurring/volume rail, no account, no CDP/Stripe. GET with no payment returns a 402 for `amount`; present an existing X-CREDIT-TOKEN to top it up in place. Idempotent on the settlement tx.
      tags:
      - Credits
      parameters:
      - name: amount
        in: query
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 1000
        description: Whole USD to fund ($1–$1000).
      - name: X-CREDIT-TOKEN
        in: header
        required: false
        schema:
          type: string
        description: Optional existing pzc_ token to top up in place.
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          type: string
        description: Base64 x402 PaymentPayload to fund the balance.
      responses:
        '200':
          description: Balance funded; a new mint returns the raw credit token once.
          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'
        '402':
          description: Payment required — accepts[0].maxAmountRequired carries the amount in USDC atomic units.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402PaymentRequired'
        '400':
          description: Invalid amount.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-sdk-group: credits
      x-sdk-method: topup
  /api/v1/storefront/credits/balance:
    get:
      operationId: creditBalance
      summary: Read a prepaid credit balance + ledger
      description: Return the balance and recent ledger for the credit token in the X-CREDIT-TOKEN header. No payment; the token is the credential (never a query param).
      tags:
      - Credits
      parameters:
      - name: X-CREDIT-TOKEN
        in: header
        required: true
        schema:
          type: string
        description: The pzc_ credit token.
      responses:
        '200':
          description: Balance + ledger.
          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: credits
      x-sdk-method: balance
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:
    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
  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