API Reference

The BuzzList public API lets you join waitlists and look up signup positions from anywhere — your own site, a CLI, a script, or an AI agent. No authentication. CORS-friendly. Rate-limited per IP.

OpenAPI 3.1 spec

Conventions

Base URL: https://buzzlist.app
All request and response bodies are JSON.
No authentication is required for any endpoint listed here.
CORS is open (Access-Control-Allow-Origin: *); preflight OPTIONS is supported.
Errors use a stable shape: { "error": "<code>" }.

Rate limiting

Endpoints are rate-limited per client IP over a rolling one-minute window. Signup also has a tighter per-(IP, waitlist) limit so a single noisy source can't exhaust one waitlist's quota. Per-endpoint numbers are listed below under each endpoint.

When a limit is exceeded the API returns HTTP 429 with body { "error": "rate_limited" }. Back off and retry after roughly the remainder of the current minute. Limits are subject to change; treat the documented numbers as a guideline, not a contract.

POST/api/waitlist/{slug}/signup

Join a waitlist

Adds an email to the specified waitlist. Returns the new signup’s position and a personal referral link. If the email is already on the waitlist, returns 409 with the existing record so you can show the same confirmation UI.

Rate limit: 10 / min per (IP, slug); 30 / min per IP overall

Example

curl -X POST https://buzzlist.app/api/waitlist/<slug>/signup \
  -H "content-type: application/json" \
  -d '{"email":"someone@example.com","name":"Optional","ref":"optional-referral-code"}'

Responses

201Signup created.

{
  "signup": {
    "position": 42,
    "referralCode": "abc123",
    "referralLink": "https://buzzlist.app/<slug>?ref=abc123",
    "referralCount": 0
  },
  "totalSignups": 42
}

409Email already on the waitlist. Body contains the existing signup record (same shape as 201).

400{"error": "invalid_email"} or {"error": "invalid_body"}

403{"error": "PLAN_LIMIT_SIGNUPS_<TIER>"} when the owner’s plan is at its signup cap.

404{"error": "not_found"} when the slug does not exist.

429{"error": "rate_limited"}

GET/api/waitlist/{slug}/position

Look up signup position

Returns the current queue position and referral state for an email already on a waitlist. Useful for building a “check my position” UI without storing the position client-side.

Rate limit: 30 / min per IP

Example

curl "https://buzzlist.app/api/waitlist/<slug>/position?email=someone@example.com"

Responses

200Current position.

{
  "position": 36,
  "signupOrder": 42,
  "referralCount": 2,
  "referralCode": "abc123",
  "referralLink": "https://buzzlist.app/<slug>?ref=abc123",
  "queueMode": "referral-weighted"
}

400{"error": "missing_email"}

404{"error": "not_found"} — slug unknown or email not on this waitlist.

429{"error": "rate_limited"}

GET/{slug}/data

Public waitlist JSON

Returns the same public information shown on the waitlist page, as JSON. Handy for building previews, embeds, or agent-driven flows without parsing HTML. Cached for 60 seconds at the edge.

Example

curl https://buzzlist.app/<slug>/data

Responses

200Public waitlist data.

{
  "slug": "my-launch",
  "name": "My Launch",
  "headline": "Coming this fall",
  "description": null,
  "signupCount": 128,
  "queueMode": "fifo",
  "referralsEnabled": true,
  "branding": {
    "primaryColor": "#D4870F",
    "ctaText": "Join the waitlist",
    "successMessage": "You're on the list!"
  },
  "createdAt": "2026-04-01T12:00:00.000Z"
}

404{"error": "not_found"}