Integration Guide

This guide walks through embedding Revel in a product directory like Arcapush— a "Revel Check" on listing edit and founder dashboard. Use the Partner REST API, not MCP. All calls are server-side.

1. Apply at /partners with your platform domain and contact email.
2. After admin approval, receive a key starting with rvl_pk_ (shown once — store in your secrets manager).
3. Whitelisted partners run audits at no per-call charge; paid partners use prepaid credits.

REVEL_PARTNER_API_URL=https://tryrevel.xyz
REVEL_PARTNER_API_KEY=rvl_pk_...    # never expose to the browser
REVEL_CACHE_TTL_HOURS=24

Founder clicks "Run Revel Check"
  → Your API route (e.g. POST /api/listings/:id/revel-check)
    → Revel POST /api/partner/v1/analyze  { url: listing.website_url }
    → Poll GET /api/partner/v1/report/:id every 3s (1–3 min)
    → Cache score + top blindspots on listing (24h TTL)
    → Display insights only — do not auto-edit listing fields

const REVEL = process.env.REVEL_PARTNER_API_URL ?? "https://tryrevel.xyz";
const KEY = process.env.REVEL_PARTNER_API_KEY!;

export async function revelAnalyze(url: string) {
  const res = await fetch(`${REVEL}/api/partner/v1/analyze`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url }),
  });
  if (!res.ok) throw new Error((await res.json()).error ?? res.statusText);
  return res.json() as Promise<{ analysisId: string; poll: string }>;
}

export async function revelPollReport(analysisId: string, maxMs = 180_000) {
  const start = Date.now();
  while (Date.now() - start < maxMs) {
    const res = await fetch(`${REVEL}/api/partner/v1/report/${analysisId}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    const data = await res.json();
    if (data.status === "completed" && data.report) return data;
    if (data.status === "failed") throw new Error(data.error ?? "Analysis failed");
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error("Revel analysis timed out");
}

Store audit results on your listing record. Example schema additions:

revel_score            INTEGER
revel_summary          TEXT
revel_top_blindspots   JSONB      -- top 5 items
revel_analysis_id      TEXT
revel_checked_at       TIMESTAMPTZ
revel_cache_expires_at TIMESTAMPTZ

Forbidden: auto-updating title, problem statement, description, or any user-authored listing copy. Revel is display-only guidance.

• RevelCheckPanel on listing edit + founder dashboard
• States: idle → loading (~2 min) → score + top blindspots
• Show "Checked X ago" when cache is valid; secondary "Run again" CTA
• Map messagingblindspots to "Update problem statement / tagline" hints

Reference output: Arcapush genesis report (Reveal Index 55, 8 blindspots).

• 401 — invalid or missing API key
• 402 — paid partner, no credits remaining
• 403 — application pending; contact Revel admin
• 429 — rate limit (30/min per partner); retry after 1 minute

Arcapush is seeded as arcapush.com (whitelisted). Revel admin approves in Mission Control → Partners, then issues the API key. With 100+ products, cache aggressively (24h) and surface only the Reveal Index plus top blindspots — full Blueprint stays in Revel for founders who want depth.