Developers
The REVEX Data API
In plain terms: get your review data into your own reports and spreadsheets. Technically: a read-only, organization-scoped JSON/CSV API for catalog, shared reviews, partnerships and trust-seal analytics — ready for any dashboard, warehouse or BI tool.
Authentication
Every request carries a bearer key created in your dashboard under Storefront → Analytics API. Keys are shown once, hashed at rest, revocable at any time, and can never write data.
Request
curl -s -H "Authorization: Bearer revex_your_key_here" \ "https://review-sync-harmony.lovable.app/api/public/v1/reviews?direction=received&limit=25"
Plain English: paste your key where it says revex_your_key_here. If the key is wrong or revoked, you get a 401 and nothing else.
Scopes
analytics:read— summary and trust-seal analyticsproducts:read— catalog rowsreviews:read— owned and received reviewspartnerships:read— exchange relationships
New keys get all four read scopes. Rate limit: 600 requests per 5 minutes per key.
Endpoints
Five read endpoints, one JSON envelope, cursor-free paging.
/api/public/v1/summaryOrganization snapshot: product count, owned reviews, average rating, placements.
One call that tells you how big your catalog and review pool are right now.
Params: —
/api/public/v1/productsYour catalog rows with external ids, handles, vendors and local review counts.
Your product list, the same one REVEX matches reviews against.
Params: limit (1–100, default 50) · page (default 1) · q (title search)
/api/public/v1/reviewsdirection=received returns reviews published onto your products; direction=owned returns approved reviews you own.
Either the reviews other companies shared with you, or the reviews you own and syndicate out.
Params: direction (received | owned) · product (your external product id) · min_rating (1–5) · since (ISO timestamp) · limit, page
/api/public/v1/partnershipsExchange relationships with status, counterparty, approval and revocation dates.
Who you're connected to, which direction it flows, and whether it's live.
Params: limit · page
/api/public/v1/badge-analyticsDaily trust-seal impressions and clicks, optionally grouped by product or variant.
How often your REVEX seal was seen and clicked, by day or by product.
Params: days (1–180) · format (json | csv) · group (daily | products | product_variants)
Response shape
Successful responses always include ok, paging fields and data. Reviews are returned with their provenance link so you can always trace a review back to its origin.
{
"ok": true,
"direction": "received",
"page": 1,
"limit": 25,
"has_more": true,
"data": [
{
"placement_id": "b1c2…",
"placed_at": "2026-08-28T14:02:11.000Z",
"product_external_id": "brooks-ghost-18",
"product_title": "Brooks Ghost 18",
"review": {
"id": "9f3a…",
"rating": 5,
"title": "Best daily trainer I've owned",
"body": "Third pair of Ghosts…",
"reviewer_display_name": "Marcus T.",
"verified_purchase": true,
"incentivized": false,
"written_at": "2026-07-04T18:41:00.000Z",
"source_system": "shopify",
"provenance_url": "/provenance/9f3a…"
}
}
]
}Errors
Errors are JSON, never HTML, and always carry a stable machine-readable code.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A query parameter is missing or out of range. |
| 401 | unauthorized | No key, malformed key, or the key was revoked. |
| 403 | forbidden_scope | The key is valid but wasn't granted that scope. |
| 429 | rate_limited | Over 600 requests in 5 minutes. Retry after 60 seconds. |
| 503 | unavailable | Temporary backend issue — retry with backoff. |
Outbound webhooks
Instead of polling, register an HTTPS endpoint in Integrations and we push events to you as they happen — partnership decisions, held placements, imported reviews, matching that needs review, disputes, questions and sync failures.
Every request is a JSON POST with X-Revex-Event, X-Revex-Delivery, X-Revex-Timestamp and X-Revex-Signature headers. The signature is sha256= followed by an HMAC-SHA256 of the raw request body, keyed with your endpoint's signing secret. Compare it before trusting the payload.
Answer with any 2xx status. Anything else is retried with backoff (1m, 5m, 30m, 2h, 6h); after repeated failures the endpoint is switched off and flagged in your dashboard, where you can also inspect and redeliver individual attempts.
POST https://hooks.your-store.com/revex
X-Revex-Event: partnership.approved
X-Revex-Delivery: 8b1f...c2
X-Revex-Signature: sha256=4f9c...ab
{
"id": "8b1f...c2",
"event": "partnership.approved",
"created_at": "2026-09-04T02:40:11.482Z",
"data": {
"organization_id": "…",
"kind": "partnership_approved",
"title": "Brooks approved your request",
"href": "/partnerships",
"entity_type": "partnership",
"entity_id": "…"
}
}What the API will never return
Privacy is structural, not a setting.
No reviewer emails, phone numbers, order numbers, IP addresses or raw source payloads. Reviewer identity is limited to the display name and coarse location the original store already published.
Analytics are aggregate-only counts by day, product and seal variant — there is no visitor-level tracking anywhere in REVEX.
Keys are scoped to a single organization. There is no cross-organization read, and no write surface at all. See roles & data privacy.
