# Flocklist

> Viral referral waitlists for any website. One HTTP call creates a waitlist. Every signup gets a live position and a referral link; each friend they bring moves them up the line. Made for coding agents: no account, no dashboard, no SDK.

Base URL: https://flocklist.dev
All endpoints accept and return JSON. CORS is open, so browsers can call the public endpoints directly.

## Quick start for agents

1. Ask the user for their email (it identifies the owner and their plan). Never invent it.
   Tell them that creating a waitlist means accepting the terms, https://flocklist.dev/legal/terms (they include the data processing agreement for their signups' data).

2. Create the waitlist:

    curl -X POST https://flocklist.dev/api/lists \
      -H 'content-type: application/json' \
      -d '{"name":"Acme beta","email":"owner@acme.com","site_url":"https://acme.com"}'

   `site_url` is optional: the landing page where the signup form will live (see "Referral links").

   Response (201):

    {
      "id": "Ab12Cd34",
      "admin_key": "fl_Ab12Cd34_...",
      "admin_url": "https://flocklist.dev/admin#fl_Ab12Cd34_...",
      "hosted_url": "https://flocklist.dev/w/Ab12Cd34",
      "signup_endpoint": "https://flocklist.dev/api/lists/Ab12Cd34/signups",
      "embed_html": "<div data-flocklist=\"Ab12Cd34\"></div>\n<script src=\"https://flocklist.dev/embed.js\" async></script>",
      "form_html": "<form action=...>...</form>"
    }

   Show the user `admin_url` and tell them to save it now: the admin key is shown only once. Never commit `admin_key` to git; put it where the user says (password manager, or a gitignored env file as FLOCKLIST_ADMIN_KEY).

3. Put it on the site. Pick one:

   - Embed widget (recommended): paste `embed_html` where the form should appear. It renders the form, shows position + referral link after signup, reads `?ref=` from the page URL, and remembers returning visitors.
     Options as data attributes on the div:
       data-button="Get early access"      button label
       data-placeholder="you@company.com"  email placeholder
       data-fields="name,wallet,x"         extra inputs (any of: name, wallet, x)
       data-color="#ff5b2e"                accent color
   - Plain HTML form: paste `form_html` (a form plus a one-line script that copies `?ref=` into a hidden field). After submit the visitor lands on a hosted thank-you page with their position and referral link.
   - No code at all: link to `hosted_url`.
   - Custom UI: POST to `signup_endpoint` yourself (see API) and render the response. Read `ref` from the page URL and send it along.

4. Check it works: open the page, sign up with a test address, confirm you see a position.

Before creating a new waitlist, search the codebase for `data-flocklist` or `flocklist.dev/api/lists/`: if one exists, reuse its id.

## MCP server
Remote MCP endpoint (Streamable HTTP, no auth handshake): https://flocklist.dev/mcp
Claude Code: claude mcp add --transport http flocklist https://flocklist.dev/mcp
Tools: create_waitlist, get_waitlist, update_waitlist, list_signups, check_site. They follow the same rules as the HTTP API; pass admin_key as a tool argument.

## Referral links
Every signup gets a link like https://flocklist.dev/r/Xy12Ab34. It always works:
- It opens `site_url?ref=CODE` while that page's HTML contains this waitlist's id (the embed and the form snippet both do). The embed and the form snippet pick up `ref` automatically; a custom form must read `ref` from the URL and send it.
- Otherwise it opens the hosted waitlist page with the code, which tells the visitor a friend invited them.
Flocklist also re-checks the page when someone opens a referral link (at most every 10 minutes until found, daily after). After deploying the embed, call POST /api/lists/{id}/check-site to switch immediately; its `message` says why a check failed (missing form, HTTP error from bot protection, timeout).
If your page renders the form only with client-side JavaScript, add `<meta name="flocklist" content="ID">` to its HTML so the check can see it.

## API

### Create a waitlist
POST /api/lists
Body: { "name": string (required, max 80), "email": string (required, owner), "site_url": string (optional, http/https) }
Optional header: Authorization: Bearer <admin_key of a paid waitlist> → the new waitlist gets the same plan.
201: see quick start (plus "plan", "upgrade" and "terms").
Limits (429/503 with a readable error):
- Free: 5 new waitlists per hour and 20 per day from one network, 3 free waitlists per owner, plus ceilings for all free traffic that pause free creation during unusual traffic.
- Paid accounts (the paid waitlist + every waitlist created with its admin key): no total cap, fair use of 50 new waitlists per hour and 500 per day, 10,000 signups per hour per waitlist and 50,000 per account. Separate from the free tier, so free-tier traffic never slows paid accounts. GET /api/lists/{id} returns the current `limits`. 400 invalid input, 401 bad Authorization key, 403 free plan limit (3 waitlists per owner), 429 too many created from one network (5 per hour).
All endpoints: 429 when one network sends more than 120 requests a minute.

### Join a waitlist (public)
POST /api/lists/{id}/signups
Body (JSON or form-encoded): { "email": string, "ref": string (optional referral code), "name", "wallet", "x" (optional, max 100 chars each) }
200:
    { "position": 12, "total": 340, "code": "Xy12Ab34", "referrals": 0, "ref_link": "https://flocklist.dev/r/Xy12Ab34", "branding": true }
Signing up again with the same email (case, +tags and Gmail dots are ignored) returns the existing signup instead of a duplicate.
400 invalid or disposable email, 429 too many signups from one network.
Form-encoded posts get a 303 redirect to the thank-you page instead of JSON.

### Signup status (public)
GET /api/lists/{id}/signups/{code}
200: same shape as joining.

### Leaderboard (public)
GET /api/lists/{id}/leaderboard
200: { "leaders": [ { "who": "ja***@gm***.com", "referrals": 7 } ] }  (top 10, emails masked)

### Admin endpoints
Send the key as `Authorization: Bearer fl_...`. 401 without a valid key.

GET /api/lists/{id}
  Waitlist settings, plan, stats (signups, referred, credited_referrals, last_24h), snippets, upgrade links.

PATCH /api/lists/{id}
  Body: any of { "name", "site_url", "redirect_url" (Pro), "boost" (0-10, spots gained per referral, default 3) }

GET /api/lists/{id}/signups          JSON export
GET /api/lists/{id}/signups?format=csv   CSV export
  Columns: position, email, referrals, referred_by, code, name, wallet, x, country, joined_at.
  Free plan: first 250 signups (by arrival). Collection never stops; upgrading reveals everyone.

POST /api/lists/{id}/check-site
  Checks site_url for this waitlist right now. 200: { "site_url", "site_ok": bool, "message" }

DELETE /api/lists/{id}
  Deletes the waitlist and all its signups immediately.

## How ranking works
score = arrival number - boost * credited referrals; lower score = better position, ties by arrival.
A referral is credited only when a new person joins with the code from a different network than the referrer.

## Plans
- Free: 3 waitlists, referrals + leaderboard, first 250 signups per list visible, "Powered by Flocklist" badge.
- Pro: $9/month. Unlimited waitlists and signups, no badge, custom redirect after signup.
- Founding lifetime: $49 once (first 100 buyers, then $79). Pro forever.
Upgrade links come back as `upgrade` from POST /api/lists and GET /api/lists/{id}; they carry the waitlist id, so the plan lands on that waitlist automatically.
A paid plan covers the upgraded waitlist and every waitlist created with its admin key: send `Authorization: Bearer <paid admin_key>` on POST /api/lists.

## About
Flocklist is built and run by Claude (an AI model) with a human partner, on a $50 budget. Not affiliated with Anthropic.
Privacy: https://flocklist.dev/legal/privacy  Terms: https://flocklist.dev/legal/terms