API · v1
PricePolls API
Programmatic, cursor-paginated access to the PricePolls catalog, accepted observations, and rolled-up market factors. Designed to drop directly into Obsydian Apex's pricing pipeline without translation.
Auth
All endpoints require a Bearer API key in the Authorization header. Create a key at /settings/api-keys and grant it the scopes you need.
curl -H "Authorization: Bearer pp_xxxxxxxx_yyyy..." \ https://your-host/api/v1/items
Available scopes:
items:readobservations:readaggregates:readmarket-factors:readwebhooks:write(managed via the UI in v1)
Pagination
Every listing endpoint returns { data, nextCursor, _meta }. When nextCursor is non-null, pass it back as?cursor=… to fetch the next page. pageSizedefaults to 50 and may be raised to 200.
GET /api/v1/items
Catalog of active items with Apex-compatible identifiers.
categoryCode— restrict to one category codeupdatedSince— ISO-8601 timestamp
curl -H "Authorization: Bearer $KEY" \ "https://your-host/api/v1/items?categoryCode=FCC&pageSize=100"
GET /api/v1/observations
Stream of accepted price submissions, shaped for apex_price_observations. Notes are private and never included. Synthetic / demo submissions are filtered out — only contributor-submitted real-world prices appear here.
since— only observations accepted at or after thisregionLevel+regionCode— restrict by regionitemSlugorcategoryCode+lineCode
curl -H "Authorization: Bearer $KEY" \ "https://your-host/api/v1/observations?regionLevel=ZIP®ionCode=60601"
GET /api/v1/aggregates
Time-series of per-(item × region × periodEnd) aggregate snapshots. Apex tenants pull this for PricePolls-derived price profiles over time. Recompute runs hourly; each calendar day produces at most one row per (item, region).
itemIdoritemSlug— required (one of)regionLevel+regionCode— restrict to one regionsince/until— ISO-8601 date or timestamp; default = last 12 months
curl -H "Authorization: Bearer $KEY" \ "https://your-host/api/v1/aggregates?itemSlug=fcc-carp-better-replace®ionLevel=ZIP®ionCode=60601&since=2026-01-01"
GET /api/v1/export
Bulk CSV download of observations or aggregate snapshots, streamed chunked. Same filter semantics as the per-resource read endpoints. Hard-capped at 250k rows per request — paginate via the JSON endpoints for larger backfills.
type—observationsoraggregates(required)format—csv(default;parquetreserved for future)- Plus all filters from the underlying endpoint (
since,until,itemSlug,regionLevel+regionCode, etc.)
curl -H "Authorization: Bearer $KEY" \ "https://your-host/api/v1/export?type=observations&since=2026-01-01" \ -o observations.csv
Tier requirement: SUBSCRIBER or higher (same as the underlying endpoint). Plus the corresponding :read scope on the API key.
GET /api/v1/market-factors
Per-region labor / material / equipment multipliers vs. national baseline, shaped for apex_zip_market_factors.
regionLevel+regionCode— restrictsince— only rows computed at or after this
curl -H "Authorization: Bearer $KEY" \ "https://your-host/api/v1/market-factors?since=2026-05-01"
Webhooks
Subscribe to events at /settings/webhooks. Each delivery is signed with HMAC-SHA256 over {unix}.{body} using a per-endpoint secret. Verify the X-PricePolls-Signature header on receipt.
X-PricePolls-Signature: t=1715200000,v1=8b9c…d3a
X-PricePolls-Event: OBSERVATION_ACCEPTED
{ "deliveryId": "...", "event": "OBSERVATION_ACCEPTED", "occurredAt": "...", "data": { ... } }Available events:
OBSERVATION_ACCEPTED— a moderator accepted a submissionMARKET_FACTOR_UPDATED— region multipliers recomputedITEM_UPDATED— item created from a proposal (more changes in later versions)
Errors
{ "error": { "code": "unauthorized", "message": "Missing or invalid API key." } }Codes:unauthorized (401),forbidden (403),bad_request (400),not_found (404).