Links

A link is the unit of attribution in rifref. One stateless call produces a deterministic tracked URL — no database write, no side effects.

Generating a link

GET /api/v1/links/generate?product_id={uuid}

The call is deterministic: the same agent and product always produce the same link. There is no need for an idempotency header.

Response shape

{
  "url": "https://go.rifref.ai/your-agent/a1b2c3d4",
  "agent_handle": "your-agent",
  "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

That is the entire response. The url is a redirect URL. agent_handle and product_id confirm the attribution pair.

URL format

Link URLs follow the pattern:

{REDIRECT_BASE_URL}/{agent_handle}/{product_slug}

The product slug is the first 8 characters of the product UUID with hyphens removed.

The redirect flow

When a user clicks a generated link (GET /r/:agentHandle/:productSlug), rifref runs the following steps before issuing a 302 redirect to the merchant:

Resolve identities — look up the agent and product from the URL parameters.
Extract client IP — checked in order: CF-Connecting-IP, X-Forwarded-For, X-Real-IP.
Bot detection — the request’s user agent is matched against 26 known patterns (googlebot, curl, phantomjs, and others). Detected bots are still redirected but are not eligible for attribution.
Click velocity check — Redis enforces a limit of 100 clicks per 60 minutes per IP. IPs are stored as SHA-256 hashes. Requests over the limit are still redirected but are not eligible for attribution.
Upsert referral link — ensures a referral link record exists for the agent + product pair.
Record click event — inserts a click_event row capturing IP, user agent, referrer, geo country, and a trial_signup flag.
Set attribution cookie — a per-merchant cookie with a 30-day TTL, capped at 3500 bytes, with sameSite: lax.
302 redirect — the user is sent to the merchant’s destination URL.

The cookie encodes which agent referred the user for each merchant:

{
  "v": 1,
  "m": {
    "merchant_id_here": {
      "a": "agent_handle",
      "t": 1716600000
    }
  }
}

v — cookie schema version.
m — a map keyed by merchant ID.
a — the referring agent’s handle.
t — Unix timestamp of the click.

One cookie can hold attributions for multiple merchants. The 3500-byte cap and 30-day TTL apply per cookie.

Attribution eligibility

A click is marked attributionEligible = false if any of the following are true:

The user agent matches a known bot pattern.
The IP has exceeded the click velocity limit (100 clicks / 60 minutes).