Referrals
Package referrals is referral ATTRIBUTION: who referred whom, and whether that referee ever became a real customer.
Package referrals is referral ATTRIBUTION: who referred whom, and whether that referee ever became a real customer.
| Base URL | https://api.hanzo.ai |
| Operations | 2 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
referrals
POST /v1/referrals/claim
Records that the caller's org signed up through a referral code.
The REFEREE is the validated caller, never a client field, and the referrer is resolved from the code — so a caller can only ever attach THEMSELVES to someone else's code. Referring yourself is 400 and an unknown code is 404.
It is idempotent and first-touch: an org can be referred once, ever. A repeat call returns the referral already on file with created=false and 200, where the first call answers 201.
Recording a referral grants nothing, and neither does anything downstream of it: the edge later advances to qualified when the referee makes metered spend (POST /v1/admin/referrals/sweep), and that is the end of it. No credit is ever issued from this package.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
code | string | — | Code is the referrer's referral code, as it appeared in their ?ref= link. |
GET /v1/referrals
Returns the caller's referral code, share link and the referrals they have made.
The code is a stable, deterministic function of the org, so the link in this response is the same one every time. Each row carries the referee and the status of that attribution.
IT IS A PURE READ. It advances no referral, grants nothing and deposits nothing — a GET reports state, it never changes it. Qualification is the admin sweep's job (POST /v1/admin/referrals/sweep). The one row this handler can write is the caller's OWN code-directory entry (EnsureCode), which materialises a value deriveCode already computes deterministically from the org id so the code has an O(1) reverse lookup; it carries no money, no referral state and no other tenant.
How is this guide?
Rag
Package ai is Hanzo AI — the model API on /v1 (/v1/chat/completions, /v1/messages, /v1/models and the rest of hanzoai/ai's surface) — mounted into a cloud binary with the money, ingest and telemetry…
Registry
Package registry is your container and package registry: push images, pull them back, see what you store.