Observations

Submit a shelf observation

Records a crowd-sourced shelf signal — stock status, and optionally a price — for a product or offer at a store. Any API key (free or partner tier) may call this with the usual Bearer header; a caller without a key may submit anonymously with an X-Device-Token header instead (a client-generated UUID identifying the device — any UUID version is accepted, the check is purely the 8-4-4-4-12 shape). Sending both headers uses the API key. Contributing observations does not consume or grant API quota; this endpoint is rate-limited separately from the read endpoints (10 req/min per IP for anonymous and device-token callers, 60 req/min per API key for sa_live_ callers — SA-0037 —, plus 50 req/15min per IP and per device token for anonymous callers).

post/api/v1/observations

Request

  • Base URL: https://api.shelfatlas.com
  • URL: https://api.shelfatlas.com/api/v1/observations
  • Auth: one of:
    • HTTP bearer
    • API key in header X-Device-Token

Request body

OR

Response

Observation recorded.

idstring uuid required
moderation_status'approved' | 'pending_review' required

A fresh observation auto-approves when it comes from a trusted source (a partner-tier API key, or a device with enough prior approved observations); otherwise it starts pending_review. 'rejected' is a later admin-moderation outcome — this endpoint never returns it on creation.

top_reporterobject

Present only when the request resolves to an identified reporter (via reporter_clerk_id or the API key's own owner). Shape may grow; treat any field not documented on the docs page as optional.

Changes

No recorded changes to this operation across all 1 revision of this API.