Skip to main content

​
Public pixels, redirects, and short links

Orbit’s engagament surface includes a band of root-mounted endpoints — mounted directly on the API host before the /api/v1 auth middleware, so they remain callable by anonymous browsers and email clients without an API key. These endpoints are the public face for a few different artifact families, but they share one contract: the endpoint is anonymous, it always answers with content a browser can render, and it must never break the user-facing page (a 1×1 transparent GIF on error, a branded HTML error page on a bad link). PKCE and Clerk don’t apply here. The auth is HMAC-SHA256, embedded in the URL itself, and the rate limit is per-IP.

​
The contract

  • Anonymous — mounted before the /api/v1 middleware, so neither an API key nor a Clerk session is required. The recipient’s browser or email client calls the endpoint.
  • Idempotent and always-render — a pixel (goal, email open, short-link click) always answers with the transparent 1×1 GIF, even on a malformed token, so the browser never renders a broken-image glyph. A redirect (short link, referral link) always answers with either the destination URL or a small branded HTML error page, never a raw JSON error blob.

​
Endpoint families

​
Goal pixel — GET /g/:goalId/:contactId.gif

The goal pixel lets a third-party page fire a conversion event for a specific contact without carrying an API key. The tenant embeds the pixel URL, and the recipient’s browser fetches it — the HMAC sig is the only auth. The response is always a 1×1 transparent GIF, whether the conversion was recorded or rejected, so a page that embeds the pixel never renders a broken image.

​
Email open pixel — GET /p/:sig.gif

The email open pixel is the 1×1 tracking pixel embedded in outbound email. It stamps metadata.opened_at on the message row. The request must carry the signed token (sig), the message id (m), the tenant id (t), and a timestamp (ts). Format guards (expected HEX HMAC, bounded timestamp window) fail closed — but still return the GIF, so a bad mint or tampered token doesn’t produce a broken image in the recipient’s client. The referral redirect and the short-link redirect do the same thing: resolve a short code to its destination and record attribution (IP, user-agent, geolocation header). The short link is the generic mintable artifact created by POST /api/v1/links; the referral link is the same idea wired into the recipient referral program. Both preserve the same error semantics — content-negotiate to a branded HTML page when Accept: text/html so the user-facing page never returns an unstyled JSON blob.

​
Landing page render — GET /lp/:code — and its convert hook — POST /lp/:code/convert

A landing page is a published renderable block tree (hero, product grid, opt-in form, coupon) served at its public code. The convert POST marks a visit as a conversion — idempotency-key protected, rate-limited per IP. Inbound email tracking links use a signed route that 302-redirects to the real destination. The signature is HMAC-SHA256 over the encoded target, so the click pipeline can attribute the referral without an API key. As with the open pixel, the link pipeline always returns the transparent GIF on failure.