{"components":{"headers":{"RateLimit":{"description":"IETF draft-11 structured field. Same remaining/reset as the primary headers.","schema":{"example":"\"peruser\";r=48;t=27","type":"string"}},"RateLimitLimit":{"description":"Primary. Current anti-abuse request limit for this identity, separate from billing quota.\n","schema":{"example":100,"type":"integer"}},"RateLimitPolicy":{"description":"IETF draft-11 structured field. Advertised anti-abuse policy (q=capacity, w=window seconds).","schema":{"example":"\"peruser\";q=100;w=60","type":"string"}},"RateLimitRemaining":{"description":"Primary. Tokens remaining in the current window after this request.","schema":{"example":99,"type":"integer"}},"RateLimitReset":{"description":"Primary. Delta-seconds until the next token is available.","schema":{"example":27,"type":"integer"}},"RetryAfter":{"description":"Seconds until the client may retry (RFC 9110). Sent on HTTP 429; matches RateLimit-Reset.","schema":{"example":27,"type":"integer"}},"XRequestId":{"description":"Correlation id; equals problem.instance on errors.","schema":{"type":"string"}},"XStoreVersion":{"description":"Immutable PremiumPin serving snapshot used for the response.","schema":{"type":"string"}}},"parameters":{"IdempotencyKey":{"description":"Dedupes metered charges on retried requests (see billing meter idempotency).","in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string"}}},"responses":{"BadRequest":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"bad filter / no scope / unknown field or op / malformed cursor / county-not-held for wholly unloaded search or absent lookup table"},"CursorExpired":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"cursor was minted against an older snapshot; restart pagination"},"NotEntitled":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"requested owner-PII fields but the plan/entitlement doesn't allow them"},"NotFound":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"parcel or key not found"},"PaymentRequired":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"x402 v2 payment requirements for USDC on Base."},"QuotaExceeded":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"metered quota exhausted (hard cap). Includes upgrade_url."},"RateLimited":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"too many requests; retry after the window","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"ScopeTooBroad":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"scope would exceed the row/scan cap; narrow fips/state/held or add filters"},"Unauthorized":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"missing or invalid API key / session"}},"schemas":{"ApiKeyMeta":{"properties":{"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"key_prefix":{"description":"safe-to-display; NOT the secret","example":"pp_live_ab12","type":"string"},"last_used_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"}},"type":"object"},"CountyCoverage":{"additionalProperties":false,"properties":{"county_held":{"type":"boolean"},"coverage_measurement":{"additionalProperties":true,"description":"Revision-bound county measurements with explicit denominator and unknowns.","nullable":true,"type":"object"},"detail":{"type":"string"},"empty_reason":{"enum":["county-not-held"],"nullable":true,"type":"string"},"fips":{"pattern":"^[0-9]{5}$","type":"string"},"honest_empty":{"type":"boolean"},"manifest_sha256":{"nullable":true,"type":"string"},"manifest_version":{"nullable":true,"type":"string"},"slots":{"additionalProperties":{"type":"boolean"},"description":"Live-column hold booleans from the loaded table catalog. Never tax_amount or subdivision_name. A key is present only when some loaded table holds that column (plus absentee_both when both streets exist in the catalog).\n","properties":{"absentee_both":{"type":"boolean"},"ag_value":{"type":"boolean"},"assessed_value":{"type":"boolean"},"improvement_value":{"type":"boolean"},"land_use":{"type":"boolean"},"land_value":{"type":"boolean"},"living_area_sqft":{"type":"boolean"},"market_value":{"type":"boolean"},"owner_address":{"type":"boolean"},"owner_name":{"type":"boolean"},"sale_date":{"type":"boolean"},"site_address":{"type":"boolean"},"year_built":{"type":"boolean"}},"type":"object"},"store_version":{"type":"string"}},"required":["store_version","fips","county_held","slots","honest_empty"],"type":"object"},"CoverageMatrix":{"additionalProperties":false,"properties":{"coverage_measurement":{"additionalProperties":true,"description":"Revision-bound measured coverage; missing or unknown rates remain null.","nullable":true,"type":"object"},"manifest_sha256":{"nullable":true,"type":"string"},"manifest_version":{"nullable":true,"type":"string"},"slots":{"additionalProperties":{"minimum":0,"type":"integer"},"description":"FIPS-with-column counts from columns that exist on at least one loaded county table. Keys are not a frozen list. absentee_both is virtual (both streets) and appears only when both streets exist in the loaded catalog.\n","properties":{"absentee_both":{"description":"FIPS that hold both streets","minimum":0,"type":"integer"},"ag_value":{"minimum":0,"type":"integer"},"assessed_value":{"minimum":0,"type":"integer"},"improvement_value":{"minimum":0,"type":"integer"},"land_use":{"minimum":0,"type":"integer"},"land_value":{"minimum":0,"type":"integer"},"living_area_sqft":{"minimum":0,"type":"integer"},"market_value":{"minimum":0,"type":"integer"},"owner_address":{"minimum":0,"type":"integer"},"owner_name":{"minimum":0,"type":"integer"},"sale_date":{"minimum":0,"type":"integer"},"site_address":{"minimum":0,"type":"integer"},"year_built":{"minimum":0,"type":"integer"}},"type":"object"},"source":{"enum":["engine_tables"],"type":"string"},"store_version":{"type":"string"},"unit":{"enum":["fips_with_column"],"type":"string"}},"required":["store_version","source","unit","slots"],"type":"object"},"FieldSourceNote":{"description":"Source context only for a delivered nonblank county-field value. Parcel-universe year does not date the field.","properties":{"capture_receipt_sha256":{"type":"string"},"effective_year":{"description":"Null when the field's effective year is unknown.","nullable":true,"type":"integer"},"field":{"type":"string"},"fieldbook_sha256":{"type":"string"},"fips":{"pattern":"^[0-9]{5}$","type":"string"},"parcel_universe_year":{"description":"Dataset membership year, not field effective year.","type":"integer"},"release_manifest_sha256":{"type":"string"},"source_field":{"type":"string"},"source_url":{"format":"uri","type":"string"},"stage_sha256":{"type":"string"},"warning":{"type":"string"}},"required":["fips","field","source_field","source_url","warning","effective_year","parcel_universe_year","capture_receipt_sha256","fieldbook_sha256","release_manifest_sha256","stage_sha256"],"type":"object"},"Filter":{"description":"Structured filter contract accepted by the public query builder.","properties":{"filters":{"items":{"properties":{"field":{"type":"string"},"op":{"enum":["eq","ne","in","contains","starts_with","gt","gte","lt","lte","between","is_null","is_not_null"],"type":"string"},"value":{}},"required":["field","op"],"type":"object"},"type":"array"},"logic":{"default":"and","enum":["and"],"type":"string"},"order_by":{"properties":{"dir":{"default":"asc","enum":["asc","desc"],"type":"string"},"field":{"type":"string"}},"type":"object"}},"type":"object"},"Parcel":{"description":"All canonical parcel fields. The build step supplies nullable typed properties.","properties":{"access_type":{"type":["string","null"]},"acres":{"type":["number","null"]},"ag_value":{"type":["number","null"]},"assessed_value":{"type":["number","null"]},"bedrooms":{"type":["integer","null"]},"block":{"type":["string","null"]},"building_type":{"type":["string","null"]},"calc_area":{"type":["number","null"]},"census_tract":{"type":["string","null"]},"census_tract_name":{"type":["string","null"]},"cooling":{"type":["string","null"]},"county_fips":{"type":["string","null"]},"county_name":{"type":["string","null"]},"county_sub_fips":{"type":["string","null"]},"county_sub_name":{"type":["string","null"]},"deed_book":{"type":["string","null"]},"deed_instrument":{"type":["string","null"]},"deed_page":{"type":["string","null"]},"elev_avg":{"type":["number","null"]},"elev_max":{"type":["number","null"]},"elev_min":{"type":["number","null"]},"epa_dfr_url":{"type":["string","null"]},"epa_frs_id":{"type":["string","null"]},"fips":{"type":["string","null"]},"fireplaces":{"type":["integer","null"]},"firm_date":{"format":"date","type":["string","null"]},"firm_id":{"type":["string","null"]},"flood_zone":{"type":["string","null"]},"foundation":{"type":["string","null"]},"full_baths":{"type":["integer","null"]},"half_baths":{"type":["integer","null"]},"heat_fuel":{"type":["string","null"]},"heating":{"type":["string","null"]},"improvement_value":{"type":["number","null"]},"iucn_class":{"type":["string","null"]},"land_use":{"type":["string","null"]},"land_use_desc":{"type":["string","null"]},"land_value":{"type":["number","null"]},"legal_desc":{"type":["string","null"]},"living_area_sqft":{"type":["number","null"]},"lot":{"type":["string","null"]},"market_value":{"type":["number","null"]},"naics_code":{"type":["string","null"]},"num_buildings":{"type":["integer","null"]},"num_floors":{"type":["integer","null"]},"num_units":{"type":["integer","null"]},"owner_address":{"type":["string","null"]},"owner_city":{"type":["string","null"]},"owner_country":{"type":["string","null"]},"owner_name":{"type":["string","null"]},"owner_state":{"type":["string","null"]},"owner_type":{"type":["string","null"]},"owner_zip":{"type":["string","null"]},"parcel_id":{"type":["string","null"]},"parcel_id_alt":{"type":["string","null"]},"parcel_id_original":{"type":["string","null"]},"parcel_id_original_alt":{"type":["string","null"]},"parcel_type":{"type":["string","null"]},"parent_parcel_id":{"type":["string","null"]},"permit_caa":{"type":["string","null"]},"permit_cwa":{"type":["string","null"]},"permit_rcra":{"type":["string","null"]},"place_name":{"type":["string","null"]},"place_type":{"type":["string","null"]},"plss_desc":{"type":["string","null"]},"prior_deed_book":{"type":["string","null"]},"prior_deed_page":{"type":["string","null"]},"quarter_section":{"type":["string","null"]},"range":{"type":["string","null"]},"roof_cover":{"type":["string","null"]},"sale_date":{"format":"date","type":["string","null"]},"sale_price":{"type":["number","null"]},"section":{"type":["string","null"]},"siding":{"type":["string","null"]},"site_address":{"type":["string","null"]},"site_city":{"type":["string","null"]},"site_state":{"type":["string","null"]},"site_zip":{"type":["string","null"]},"source_updated":{"format":"date","type":["string","null"]},"source_vintage":{"type":["string","null"]},"stack_id":{"type":["string","null"]},"state_fips":{"type":["string","null"]},"static_bfe":{"type":["number","null"]},"tax_account":{"type":["string","null"]},"tax_district":{"type":["string","null"]},"tax_year":{"type":["integer","null"]},"township":{"type":["string","null"]},"year_built":{"type":["integer","null"]},"zoning_code":{"type":["string","null"]},"zoning_desc":{"type":["string","null"]},"zoning_subtype":{"type":["string","null"]}},"type":"object"},"PreparedArtifact":{"properties":{"artifact":{"properties":{"bytes":{"minimum":1,"type":"integer"},"expires_at":{"description":"UTC Unix timestamp","type":"integer"},"path":{"pattern":"^/v1/artifacts/[0-9a-f]{64}$","type":"string"},"rows":{"maximum":5000,"minimum":0,"type":"integer"},"sha256":{"pattern":"^[0-9a-f]{64}$","type":"string"}},"required":["path","sha256","bytes","rows","expires_at"],"type":"object"},"complete":{"type":"boolean"},"delivery_complete":{"type":"boolean"},"next_cursor":{"nullable":true,"type":"string"},"receipt":{"type":"object"},"row_cap":{"type":"integer"},"scope_coverage":{"type":"object"},"status":{"type":"string"},"store_version":{"type":"string"}},"required":["artifact","store_version","status","delivery_complete","complete","receipt"],"type":"object"},"Problem":{"description":"RFC 9457 Problem Details. Media type application/problem+json.","properties":{"bindable_fips":{"items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array"},"cap":{"type":"integer"},"code":{"description":"stable machine slug","type":"string"},"detail":{"type":"string"},"docs":{"type":"string"},"field":{"type":"string"},"instance":{"description":"= X-Request-Id","type":"string"},"meter":{"type":"string"},"op":{"type":"string"},"request_id":{"type":"string"},"retry_after_seconds":{"type":"integer"},"scope_coverage":{"$ref":"#/components/schemas/ScopeCoverage"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"example":"https://api.premiumpin.com/problems/quota-exceeded","format":"uri","type":"string"},"upgrade_url":{"type":"string"},"used":{"type":"integer"}},"required":["type","title","status"],"type":"object"},"QueryRequest":{"additionalProperties":false,"properties":{"cursor":{"description":"opaque keyset cursor from a prior response. Bound to store_version + query; else 400/410.","type":"string"},"filter":{"$ref":"#/components/schemas/Filter","description":"Structured closed filter. Combined with named slots using AND."},"limit":{"default":100,"maximum":5000,"minimum":1,"type":"integer"},"order_by":{"properties":{"dir":{"default":"asc","enum":["asc","desc"],"type":"string"},"field":{"type":"string"}},"type":"object"},"q":{"description":"Closed English question over held catalog slots. Not freehand SQL.","type":"string"},"scope":{"$ref":"#/components/schemas/QueryScope"},"select":{"description":"Return-field whitelist from the public field catalog. Private internal fields are never allowed.","items":{"type":"string"},"type":"array"},"slots":{"additionalProperties":true,"description":"Named closed-catalog slots. Combined with filter.filters using AND. tax_amount and subdivision_name are rejected.\n","type":"object"}},"required":["scope"],"type":"object"},"QueryResponse":{"properties":{"bindable_fips":{"items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array"},"count":{"description":"rows returned (<= limit)","type":"integer"},"empty_reason":{"enum":["field-not-held"],"nullable":true,"type":"string"},"field_notes":{"items":{"$ref":"#/components/schemas/FieldSourceNote"},"type":"array"},"honest_empty":{"type":"boolean"},"miss_reason":{"nullable":true,"type":"string"},"next_cursor":{"description":"pass as cursor for the next page; null on last page","nullable":true,"type":"string"},"parcels":{"items":{"$ref":"#/components/schemas/Parcel"},"type":"array"},"question_id":{"nullable":true,"type":"string"},"scope_coverage":{"$ref":"#/components/schemas/ScopeCoverage"},"store_version":{"type":"string"},"truncated":{"description":"more rows exist beyond this page","type":"boolean"},"unavailable_fields":{"description":"Named fields not held by the scoped county; present on field-not-held honest empties.","items":{"type":"string"},"type":"array"}},"required":["scope_coverage"],"type":"object"},"QueryScope":{"additionalProperties":false,"description":"REQUIRED. Exactly one of fips, state, or held bounds the search.","oneOf":[{"required":["fips"]},{"required":["state"]},{"required":["held"]}],"properties":{"fips":{"items":{"pattern":"^[0-9]{5}$","type":"string"},"maxItems":50,"minItems":1,"type":"array"},"held":{"items":{"enum":["all"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"},"state":{"items":{"pattern":"^[A-Z]{2}$","type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"type":"object"},"ScopeCoverage":{"additionalProperties":false,"description":"Shared Engine availability for the effective existing filter and type rules. All FIPS arrays are sorted and deduplicated. For resolved supported filters, bindable/unavailable/field-unavailable are disjoint and exhaust requested_fips. Available means all requested counties bindable, partial a nonempty proper subset, unavailable none. Unknown means unresolved filter, with no certified bindable/unavailable/field-unavailable classification; it is never a fallback for missing or corrupt Census authority (generation binding fails). This does not promise visited counties, nonnull fields, distinct parcel totals, or legal access. Optional nullable projections retain existing binding rules.\n","properties":{"bindable_fips":{"description":"Eligible under existing required-field/type rules, not visited on this page.","items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array","uniqueItems":true},"field_unavailable_fips":{"description":"Held geography lacking required capability.","items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array","uniqueItems":true},"legacy_fips":{"description":"Loaded/requested historical codes outside pinned current authority; not successor-jurisdiction coverage.","items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array","uniqueItems":true},"requested_fips":{"items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array","uniqueItems":true},"status":{"enum":["available","partial","unavailable","unknown"],"type":"string"},"unavailable_fips":{"description":"Requested geography without a loaded table.","items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array","uniqueItems":true}},"required":["status","requested_fips","bindable_fips","unavailable_fips","field_unavailable_fips","legacy_fips"],"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"bearerFormat":"pp_live_* / pp_test_*","description":"Authorization: Bearer pp_live_...  Never in a query string.","scheme":"bearer","type":"http"},"SessionCookie":{"description":"First-party web app only (HttpOnly, Secure, SameSite=Lax).","in":"cookie","name":"pp_session","type":"apiKey"}}},"info":{"description":"Source-level US property records through one combinable closed catalog. Read-only. Agents use API keys (Bearer) or hosted MCP OAuth. The website handles marketing, account access, and setup documentation at https://premiumpin.com/developers/#connect. Every query MUST carry a scope and is row-capped and time-bounded. Private internal datasets are never served. Each paid account has its own allowance of up to 1,000,000 delivered parcel rows per UTC calendar month across query, lookup, API, MCP, and export delivery. Questions and export operations are unlimited; each export is limited to 5,000 rows. Accounts never share this allowance. Omit-select query and export return all available canonical fields, up to 91; unheld values remain null or empty. Prepared private artifacts are the supported delivery path for CSV too large for an inline tool response. Rate-limit convention (anti-abuse, separate from billing quota): primary headers are RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (delta-seconds). The same values are also sent as IETF draft-11 structured RateLimit and RateLimit-Policy. HTTP 429 includes Retry-After with the same seconds. Remaining/limit are the live request allowance. See https://premiumpin.com/developers/quickstart/.\n","title":"PremiumPin Property Records API","version":"1.0.0","x-lifecycle":{"deprecation":"retired endpoints carry Deprecation (RFC 9745) + Sunset (RFC 8594) + Link headers, then 410.","versioning":"URL-path major (/v1). Additive-only within v1; breaking changes mint /v2."}},"openapi":"3.1.0","paths":{"/v1/artifacts/{artifact_id}":{"get":{"description":"Requires the same account authorization and current export entitlement. Rechecks suppression on retrieval. The opaque path is not a credential; downloading an existing settled artifact does not deliver new rows.\n","operationId":"getArtifact","parameters":[{"in":"path","name":"artifact_id","required":true,"schema":{"pattern":"^[0-9a-f]{64}$","type":"string"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"type":"string"}}},"description":"Exact prepared CSV bytes from the settled export.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Store-Version":{"$ref":"#/components/headers/XStoreVersion"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Retrieve a prepared CSV for this account before expiry.","tags":["query"]}},"/v1/count":{"post":{"description":"Counts rows through the same scope, filter, serving-policy, field-availability, owner-filter entitlement, and suppression boundaries as row search. It returns no parcel records and does not charge delivered-row allowance.\n","operationId":"countParcels","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"filter":{"$ref":"#/components/schemas/Filter"},"scope":{"$ref":"#/components/schemas/QueryScope"},"slots":{"additionalProperties":true,"description":"Named closed-catalog slots combined with filter using AND.","type":"object"}},"required":["scope"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"billing":{"properties":{"allowance_charged":{"const":false,"type":"boolean"},"rows_charged":{"const":0,"type":"integer"}},"required":["allowance_charged","rows_charged"],"type":"object"},"count":{"minimum":0,"type":"integer"},"scope_coverage":{"$ref":"#/components/schemas/ScopeCoverage"},"store_version":{"type":"string"},"suppression_adjusted":{"const":true,"type":"boolean"}},"required":["store_version","count","scope_coverage","billing","suppression_adjusted"],"type":"object"}}},"description":"Exact count and explicit no-charge billing state."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"413":{"$ref":"#/components/responses/ScopeTooBroad"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Exact suppression-adjusted count without parcel-row delivery or allowance burn.","tags":["query"]}},"/v1/coverage":{"get":{"description":"Walks the already-loaded engine table catalog with the same _type_is_held the query path uses. Each slot is a FIPS count of a column that exists on at least one loaded county table, not a frozen list and not health counties_loaded. Absentee is held only when both owner_address and site_address exist. Optional ?fips= returns the per-county boolean map. Does not advertise fields absent from loaded county tables (tax_amount, subdivision_name, FEMA/EPA stay out unless a table holds them). No national fill percent.\n","operationId":"getCoverage","parameters":[{"in":"query","name":"fips","required":false,"schema":{"pattern":"^[0-9]{5}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CoverageMatrix"},{"$ref":"#/components/schemas/CountyCoverage"}]}}},"description":"national slot counts, or per-FIPS boolean map when fips is set","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"FIPS-with-column hold counts from loaded engine tables. Not a fill percent.","tags":["meta"]}},"/v1/coverage/{fips}":{"get":{"description":"Same live-column catalog as GET /v1/coverage. Reports which of those slots this one FIPS actually holds. A nationally-present column this FIPS lacks is false, not invented on that table. Absentee is held only when both streets exist. Does not print a national fill percent.\n","operationId":"getCountyCoverage","parameters":[{"in":"path","name":"fips","required":true,"schema":{"pattern":"^[0-9]{5}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountyCoverage"}}},"description":"per-FIPS hold map (metadata only; no parcel rows)","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"Closed-hold slots on one county. Honest empty when the county is unheld.","tags":["meta"]}},"/v1/export":{"post":{"description":"Accepts the same scoped closed-catalog request as /v1/query. The server applies the same authentication, entitlement, suppression, metering, snapshot, and hard 5,000-row cap before streaming CSV. Omit-select CSV headers are the 91 canonical_fields in schema order; unheld values are empty cells. A named filter that is not held on the scoped county returns JSON empty + unavailable_fields, not CSV. CSV preflight carries bounded scope status/count headers; detailed arrays stay in query/empty JSON and the existing export audit entry. Unavailable-Count sums counties without tables and held counties missing required capability. These are not row, visited-county, field-fill or legally accessible-parcel counts. Delivery terminal states and geography availability are independent. The MCP wrapper preserves delivery status (complete/truncated/error; not-started for JSON/local honest empties), exposes delivery_complete and the bounded scope_coverage status/requested_count/bindable_count/unavailable_count, and sets complete only for exhausted delivery with valid available scope headers. Missing/unknown/contradictory available headers cannot certify completeness; error/truncation/disconnect overrides success. JSON empties retain full shared metadata and never claim completed CSV delivery. Local unresolved empties have unknown scope. No scope enumeration grants access or bypasses suppression. The in-band CSV terminal receipt includes field_notes for delivered nonblank county-field values with a material official source caveat. Notes identify the bound source and do not assign an inferred effective year. For prepared delivery, send X-PP-Delivery: artifact-v1 and a stable Idempotency-Key. A large result returns an account-bound artifact descriptor; retrieve its exact bytes through GET /v1/artifacts/{artifact_id} with the same account authorization before expiry. The path is not a bearer token.\n","operationId":"exportParcels","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"description":"Negotiate private prepared delivery for this paid account.","in":"header","name":"X-PP-Delivery","required":false,"schema":{"enum":["artifact-v1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/QueryResponse"},{"$ref":"#/components/schemas/PreparedArtifact"}]}},"text/csv":{"schema":{"type":"string"}}},"description":"CSV rows, a prepared artifact descriptor, or an honest-empty JSON response when a named filter field is not held on the scoped county.\n","headers":{"X-Export-Row-Cap":{"schema":{"type":"integer"}},"X-Export-Truncated":{"schema":{"enum":["false","pending"],"type":"string"}},"X-PP-Bindable-Count":{"description":"Schema-bindable geographies; not counties visited on this page. CSV only.","schema":{"minimum":0,"type":"integer"}},"X-PP-Requested-Count":{"description":"Number of deduplicated requested geographies, including loaded legacy codes. CSV only.","schema":{"minimum":0,"type":"integer"}},"X-PP-Scope-Coverage":{"description":"CSV preflight geographic/schema availability, not delivery completion.","schema":{"enum":["available","partial","unavailable","unknown"],"type":"string"}},"X-PP-Unavailable-Count":{"description":"No-table plus field-unavailable geographies. Unknown scope is not an exhaustive partition. CSV only.","schema":{"minimum":0,"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"X-Store-Version":{"$ref":"#/components/headers/XStoreVersion"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/NotEntitled"},"410":{"$ref":"#/components/responses/CursorExpired"},"413":{"$ref":"#/components/responses/ScopeTooBroad"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Bounded CSV export through the same guarded query path.","tags":["query"]}},"/v1/field-catalog":{"get":{"description":"Reports canonical names, types, legal operators, buyer-language synonyms, county availability, and the caller's owner-PII entitlement. The virtual owner_absentee field is held only when both owner and site streets are held. This metadata request does not consume the parcel-row allowance.\n","operationId":"getAccountFieldCatalog","parameters":[{"in":"query","name":"fips","required":true,"schema":{"pattern":"^[0-9]{5}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"county_held":{"type":"boolean"},"coverage_measurement":{"additionalProperties":true,"description":"Revision-bound county measurements with explicit denominator and unknowns.","nullable":true,"type":"object"},"fields":{"items":{"properties":{"alternative":{"type":"string"},"description":{"type":"string"},"entitled":{"type":"boolean"},"entitlement":{"nullable":true,"type":"string"},"held":{"type":"boolean"},"name":{"type":"string"},"ops":{"items":{"type":"string"},"type":"array"},"synonyms":{"items":{"type":"string"},"type":"array"},"type":{"type":"string"}},"required":["name","ops","synonyms","held","entitled"],"type":"object"},"type":"array"},"fips":{"pattern":"^[0-9]{5}$","type":"string"},"manifest_sha256":{"nullable":true,"type":"string"},"manifest_version":{"nullable":true,"type":"string"},"store_version":{"type":"string"}},"required":["fips","county_held","store_version","fields"],"type":"object"}}},"description":"Account-aware catalog for the requested county."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Account-aware field catalog for one county, without parcel rows.","tags":["meta"]}},"/v1/health":{"get":{"operationId":"getHealth","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"api_version":{"example":"1.0.0","type":"string"},"counties_loaded":{"type":"integer"},"coverage_measurement":{"additionalProperties":true,"description":"Revision-bound served-population measurements; missing or unknown rates remain null.","nullable":true,"type":"object"},"manifest_sha256":{"nullable":true,"type":"string"},"manifest_version":{"nullable":true,"type":"string"},"rows_estimated":{"description":"Planner statistics estimate, reported separately from rows_loaded.","type":"integer"},"rows_loaded":{"description":"Exact rows from PostgreSQL insert/delete lifecycle counters; startup fails if counters are missing or reset.","type":"integer"},"status":{"enum":["ok","degraded"],"type":"string"},"store_version":{"description":"immutable snapshot id currently served","type":"string"}},"type":"object"}}},"description":"OK","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}}},"security":[],"summary":"Liveness + served snapshot version. No auth.","tags":["meta"]}},"/v1/interpret":{"post":{"description":"Returns ready, clarify, or unsupported. Only ready includes an executable QueryRequest. Forward the returned state as previous_plan for corrections; all supplied state is revalidated and grants no authorization. Query and export retain their existing entitlement, scope, quota and row controls. ZIP filters require bounded county or state scope. Unsupported meanings never silently disappear. This endpoint is authenticated and rate limited.\n","operationId":"interpretQuestion","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"limit":{"default":100,"maximum":5000,"minimum":1,"type":"integer"},"previous_plan":{"description":"Explicit state from the previous interpretation.","type":"object"},"scope":{"$ref":"#/components/schemas/QueryScope"},"select":{"items":{"type":"string"},"type":"array"},"utterance":{"maxLength":4000,"minLength":1,"type":"string"}},"required":["utterance"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"action":{"enum":["search","lookup","export","count","field_catalog"],"type":"string"},"clarification":{"description":"Structured clarification for one unresolved span; never leftover-token residue.","type":"object"},"dropped_constraints":{"description":"Every uncompiled input constraint, with an explicit reason. Empty on complete plans.","items":{"properties":{"reason":{"type":"string"},"span":{"type":"string"}},"required":["span","reason"],"type":"object"},"type":"array"},"plan":{"description":"Existing QueryRequest when ready; null otherwise."},"plan_hash":{"type":"string"},"question":{"type":"string"},"reason":{"type":"string"},"state":{"type":"object"},"status":{"enum":["ready","clarify","unsupported"],"type":"string"}},"required":["status","action","state"],"type":"object"}}},"description":"Interpretation only; no parcel query or export executed."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"$ref":"#/components/responses/ScopeTooBroad"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Interpret a bounded property request without reading parcel rows.","tags":["query"]}},"/v1/keys":{"get":{"operationId":"listKeys","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ApiKeyMeta"},"type":"array"}}},"description":"key metadata list"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"SessionCookie":[]}],"summary":"List the account's API keys (metadata only \u2014 never the secret).","tags":["keys"]},"post":{"operationId":"createKey","requestBody":{"content":{"application/json":{"schema":{"properties":{"expires_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiKeyMeta"},{"properties":{"secret":{"description":"shown once, unrecoverable","example":"pp_live_ab12CdEf...","type":"string"}},"type":"object"}]}}},"description":"created \u2014 `secret` present only in this response"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"SessionCookie":[]}],"summary":"Mint a new API key. The full secret is returned EXACTLY ONCE.","tags":["keys"]}},"/v1/keys/{key_id}":{"delete":{"operationId":"revokeKey","parameters":[{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"revoked"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"SessionCookie":[]}],"summary":"Revoke a key. Takes effect immediately (is_active=false).","tags":["keys"]}},"/v1/parcels/{fips}/{parcel_id}":{"get":{"description":"An absent county table returns 400 county-not-held, distinct from the existing suppression-sensitive 404 for a parcel not found in a held county. MCP batch propagates county-not-held rather than converting it to found=false.\n","operationId":"getParcel","parameters":[{"in":"path","name":"fips","required":true,"schema":{"pattern":"^[0-9]{5}$","type":"string"}},{"in":"path","name":"parcel_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"field_notes":{"items":{"$ref":"#/components/schemas/FieldSourceNote"},"type":"array"},"parcel":{"$ref":"#/components/schemas/Parcel"},"store_version":{"type":"string"}},"type":"object"}}},"description":"one parcel record (projected, PII-gated, suppression-checked)","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Single parcel by spine key. Point lookup. Charges record_reveal (1).","tags":["query"]}},"/v1/query":{"post":{"description":"Provide a closed `q`, named `slots`, or a structured catalog `filter`; supplied controls combine with AND and are validated through the builder whitelist. A field not held by the scoped county returns an honest empty. Exactly one of scope.fips, scope.state, or scope.held is required; scope.held=[all] searches loaded non-Vermont counties. Omit-select rows include the 91 canonical_fields in schema order; unheld values are null. A named select keeps the requested keys and is not forced to 91. Metering: charges `search` (1) on accept and `record_reveal` per returned row. scope_coverage describes requested geography versus schema-bindable counties, independently of positive/zero rows and pagination. State scope uses the pinned current Census spine plus loaded historical counties, explicitly marked legacy. Wholly unloaded scope returns 400 county-not-held, not field-not-held or no matches.\n","operationId":"queryParcels","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}},"description":"matching parcels (projected, PII-gated by entitlement, suppression-filtered)","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/NotEntitled"},"410":{"$ref":"#/components/responses/CursorExpired"},"413":{"$ref":"#/components/responses/ScopeTooBroad"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Combinable closed-catalog query. Scope required. Row-capped. Cursor-paginated.","tags":["query"]}},"/v1/schema":{"get":{"operationId":"getSchema","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"default_limit":{"type":"integer"},"default_select":{"items":{"type":"string"},"type":"array"},"fields":{"items":{"properties":{"desc":{"type":"string"},"name":{"type":"string"},"ops":{"items":{"type":"string"},"type":"array"},"pii":{"description":"owner PII \u2014 entitlement-gated","type":"boolean"},"type":{"enum":["text","state","enum","int","number","date","virtual"],"type":"string"},"values":{"description":"enum only","items":{"type":"string"},"type":"array"}},"type":"object"},"type":"array"},"max_limit":{"type":"integer"}},"type":"object"}}},"description":"field list with types, legal ops, enum values, default_select, max_limit"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"Queryable public field catalog.","tags":["meta"]}},"/v1/usage":{"get":{"operationId":"getUsage","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"meters":{"items":{"properties":{"cap":{"nullable":true,"type":"integer"},"meter":{"enum":["search","record_reveal","api_record"],"type":"string"},"overage":{"type":"boolean"},"used":{"type":"integer"}},"type":"object"},"type":"array"},"period":{"example":"2026-07","type":"string"},"plan":{"type":"string"}},"type":"object"}}},"description":"usage per meter"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"Current UTC-month metered usage for this account only (from the meter, not the store).","tags":["meta"]}},"/x402/export":{"post":{"operationId":"x402Export","requestBody":{"content":{"application/json":{"example":{"fips":["48201"],"limit":100,"slots":{"acreage_min":5}},"schema":{"additionalProperties":false,"properties":{"fips":{"items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array"},"limit":{"maximum":5000,"minimum":1,"type":"integer"},"slots":{"type":"object"},"state":{"pattern":"^[A-Z]{2}$","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"text/csv":{"schema":{"type":"string"}}},"description":"Paid CSV export."},"402":{"$ref":"#/components/responses/PaymentRequired"},"422":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"Purchase one bounded CSV export with USDC on Base.","tags":["query"]}},"/x402/lookup":{"post":{"operationId":"x402Lookup","requestBody":{"content":{"application/json":{"example":{"fips":"12071","parcel_id":"014423C1024330130"},"schema":{"additionalProperties":false,"properties":{"fips":{"pattern":"^[0-9]{5}$","type":"string"},"parcel_id":{"minLength":1,"type":"string"}},"required":["fips","parcel_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Paid parcel lookup result."},"402":{"$ref":"#/components/responses/PaymentRequired"},"422":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"Purchase one exact parcel lookup with USDC on Base.","tags":["query"]}},"/x402/search":{"post":{"operationId":"x402Search","requestBody":{"content":{"application/json":{"example":{"limit":25,"slots":{"acreage_min":5},"state":"TX"},"schema":{"additionalProperties":false,"properties":{"fips":{"items":{"pattern":"^[0-9]{5}$","type":"string"},"type":"array"},"limit":{"maximum":100,"minimum":1,"type":"integer"},"slots":{"type":"object"},"state":{"pattern":"^[A-Z]{2}$","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}},"description":"Paid bounded search result."},"402":{"$ref":"#/components/responses/PaymentRequired"},"422":{"$ref":"#/components/responses/BadRequest"}},"security":[],"summary":"Purchase one bounded property search with USDC on Base.","tags":["query"]}}},"security":[{"ApiKeyAuth":[]},{"SessionCookie":[]}],"servers":[{"url":"https://api.premiumpin.com"}],"tags":[{"description":"Search + point lookup","name":"query"},{"description":"Health, schema, and usage","name":"meta"},{"description":"API-key management (session-authed)","name":"keys"}],"x-premiumpin-coverage":{"coverage_url":"https://api.premiumpin.com/v1/coverage","status":"promoted"}}