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:read
  • observations:read
  • aggregates:read
  • market-factors:read
  • webhooks: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 code
  • updatedSince — 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 this
  • regionLevel + regionCode — restrict by region
  • itemSlug or categoryCode + lineCode
curl -H "Authorization: Bearer $KEY" \
  "https://your-host/api/v1/observations?regionLevel=ZIP&regionCode=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).

  • itemId or itemSlug — required (one of)
  • regionLevel + regionCode — restrict to one region
  • since / 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&regionLevel=ZIP&regionCode=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 — observations or aggregates (required)
  • format — csv (default; parquet reserved 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 — restrict
  • since — 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 submission
  • MARKET_FACTOR_UPDATED — region multipliers recomputed
  • ITEM_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).