Book a live demo — see your catalog's review coverage →

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 analytics
  • products:read — catalog rows
  • reviews:read — owned and received reviews
  • partnerships: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.

GET
/api/public/v1/summary
analytics:read

Organization snapshot: product count, owned reviews, average rating, placements.

One call that tells you how big your catalog and review pool are right now.

Params: —

GET
/api/public/v1/products
products:read

Your 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)

GET
/api/public/v1/reviews
reviews:read

direction=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

GET
/api/public/v1/partnerships
partnerships:read

Exchange 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

GET
/api/public/v1/badge-analytics
analytics:read

Daily 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.

StatusCodeMeaning
400invalid_requestA query parameter is missing or out of range.
401unauthorizedNo key, malformed key, or the key was revoked.
403forbidden_scopeThe key is valid but wasn't granted that scope.
429rate_limitedOver 600 requests in 5 minutes. Retry after 60 seconds.
503unavailableTemporary 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.