API reference
Every route, with behaviour, limits and examples.
The generated contract is openapi/getwait.v1.json (see api-versioning.md); this page adds the behaviour around it. All routes live under
/api/v1, take Authorization: Bearer <key>, and answer errors with the
envelope { error: { code, message, requestId, details? } }.
Waitlists
POST /waitlists — secret key
{
"name": "Product Launch",
"slug": "launch",
"settings": { "double_opt_in": true }
}
name: 1–100 chars, trimmed.slug(optional): kebab-case (a-z,0-9, single hyphens), ≤ 64 chars, unique per project. A taken explicit slug is409 conflict. Omitted: derived fromname, with-2,-3, ... appended on collision (up to 10 tries, then409).settings(optional, unknown keys rejected), defaults shown:referral: { enabled: false, positions_per_referral: 1, max_bumps? }(referrals and referral ranking are opt-in; with them off,positionis plain join order),double_opt_in: true,captcha_required: false,redirect_url_allowlist: [](absolute http(s) URLs, ≤ 20),redirect_url: null(where a confirmed signup is sent; must match the allowlist or the request is422),physical_address: null(one line, ≤ 300 chars, printed in email footers; optional now, required before sending promotional email),leaderboard: { enabled: false, show_names: false }(see the leaderboard route below).
An allowlist entry admits URLs with the same origin (scheme, host, port) and a path that starts with the entry's path; an origin-only entry admits any path on that origin. URLs with credentials, other schemes, or control characters never match. The rule is applied again at redirect time.
201 → { id, name, slug, settings, archived, archivedAt, createdAt }.
GET /waitlists/:id — secret key
200 → same shape. Unknown id, or a waitlist of another project: 404.
Archived waitlists are returned too.
PATCH /waitlists/:id — secret key
{
"name": "Product Launch 2",
"settings": {
"double_opt_in": false,
"referral": { "positions_per_referral": 3 }
}
}
Send at least one of:
name: same rules as create.settings: same keys and validation as create, merged into the stored settings. Omitted keys keep their value (referralandleaderboardmerge one level deep).redirect_urlandphysical_addressclear withnull. The redirect rule is checked against the merged result, so shrinking the allowlist below the currentredirect_urlis422. Unknown keys, at any level, are422.archived:truearchives,falserestores (see below).
The slug is immutable: sending it is 422. 200 → the waitlist.
Safe to retry. Applying the same body again leaves the same state and
returns the same waitlist. Two writers racing are last-write-wins per
field: each request locks the row, merges only the keys it sent, and writes,
so a name change and a captcha change from different clients both survive. There
is no If-Match/version check.
Changing double_opt_in affects only future joins. People already on the
list keep their status, and confirmation emails already queued stay valid.
Turning it off does not mark pending signups as verified; turning it on does
not demote verified ones.
DELETE /waitlists/:id — secret key
Archives the waitlist (soft delete); nothing is erased. 200 → the waitlist
with archived: true and archivedAt. Idempotent: archiving an archived
waitlist returns it unchanged, keeping the first archivedAt.
While archived:
POST /waitlists/:id/signupsanswers409 waitlist_archived, including for an address already on the list.- Reads (
GET /waitlists/:id, signup lookups and listings, the leaderboard) andGET /waitlists/:id/exportkeep working. Existing confirm links keep working. Signup erasure keeps working. - It no longer counts toward the plan's waitlist limit.
To erase the data itself, erase signups, or delete the project in the dashboard.
POST /waitlists/:id/restore — secret key
Reverses an archive (PATCH with archived: false is equivalent).
Idempotent: restoring an active waitlist returns it unchanged. The restored
waitlist counts toward the limit again, so a free project that already has 2
active waitlists gets 402 plan_limit_reached and cannot get around the limit
by archiving, creating, and restoring.
Signups
POST /waitlists/:id/signups — publishable or secret key
{
"email": "ada@example.com",
"ref": "7KQ4M2XA",
"source": { "utm_source": "hn", "referrer": "https://news.ycombinator.com/" }
}
email: trimmed; domain lowercased and IDNA-encoded; local part kept as typed. Dot-atom local parts and DNS host names only (no quoted locals, IP literals, or single-label domains); ≤ 254 chars. Invalid →422validation_failedwith an issue atbody/email.ref(optional): a referral code from the same waitlist. A new signup with a valid code starts apendingreferral; it becomesconvertedonly when this signup confirms its email. Unknown codes (including codes of other waitlists) are ignored and the response is identical. Rejected referrals (own address, address already on the list, referrer unverified, same ip hash as the referrer) are stored with a reason and earn nothing.positionalready includes the referrer's bump: each converted referral moves a signup uppositions_per_referralplaces (capped bymax_bumps), ties going to the signup that moved.source(optional):utm_source|utm_medium|utm_campaign|utm_term|utm_content(≤ 200 chars each) andreferrer(≤ 2048). Other keys →422.
201 → { id, position, referralCode, status } for a new signup.
Idempotent by email. Joining again with an address that normalizes to the
same value returns 200 with the existing signup in the identical shape; no
second row is created, even under concurrent requests. Retrying is always
safe, so there is no Idempotency-Key header.
Position is computed on read, never stored: the 1-based rank by
(created_at, id) among the waitlist's live signups (not soft-deleted, status
not removed). Ties on created_at break by id ascending; ids are UUIDv7,
so that is creation order within a process. null only for a removed signup.
Referral code: 8 chars from 23456789ABCDEFGHJKMNPQRSTUVWXYZ (no
0/O/1/I/L), unique per waitlist.
Unknown waitlist, or one owned by another project: 404.
GET /waitlists/:id/signups/by-code/:referralCode — publishable or secret key
200 → { position, status, referralCode, referralCount }. The referral code
is the bearer proof for a signup's own status, so the response never carries
an email. referralCount counts converted referrals only. Unknown code, or
the code of an erased signup: 404.
GET /waitlists/:id/leaderboard?limit= — publishable or secret key
200 → { entries: [{ rank, referralCount, name }] }. limit is 1–100
(default 10). Ranked by converted referrals, descending; ties go to the
earliest verifiedAt, then to the lower signup id. Only signups with at least
one converted referral appear; erased and removed signups never do.
name is Anonymous #<rank> by default. With leaderboard.show_names: true
it is the first character of the email's local part plus *** (j***); the
length and domain are never revealed. The response carries no emails, referral
codes or ids. leaderboard.enabled: false answers 404, the same as an
unknown waitlist.
Caching and staleness. The response has Cache-Control: private, max-age=30, an ETag and Vary: Authorization. A repeat request with a
matching If-None-Match gets 304. Treat the board as up to 30 seconds
stale (browsers and SDKs may serve it without asking); there is no
server-side cache, so each uncached request reads the current data. private
keeps shared caches from replaying one key's answer for another.
GET /waitlists/:id/signups/:signupId — secret key
200 → { id, waitlistId, email, emailOriginal, emailNormalized, status, referralCode, position, referralCount, referredBySignupId, verifiedAt, source, ipHash, createdAt, deletedAt }. Erased signups return their
tombstone (PII fields null, status removed).
GET /waitlists/:id/signups — secret key
Query: limit (1–200, default 50), cursor, status
(pending|verified|removed), q (case-insensitive part of the email address, ≤ 100),
created_after (ISO datetime, exclusive).
200 → { signups: [<detail>], next_cursor }. Sorted by (created_at, id)
ascending, so concurrent inserts never cause skips or duplicates. Pass
next_cursor back as cursor; null means the last page. The cursor is
opaque; a malformed or tampered one is 400 invalid_cursor. Erased signups
are not listed.
GET /waitlists/:id/export?format=csv|json — secret key
Downloads every live signup, streamed (memory use does not grow with the
list). format defaults to csv. Limited to 5 exports per hour per API
key, and every export is written to the audit log (signups_exported ops
event: key id, waitlist, format; never addresses).
Fields: id, email, status, created_at, verified_at, referral_code,
referral_count (converted referrals), utm_source, utm_medium,
utm_campaign, utm_term, utm_content, referrer. Timestamps are ISO 8601
UTC; rows are ordered by created_at, then id.
- CSV is RFC 4180 (CRLF, quoted when needed). A cell that starts with
=,+,-,@, tab or CR gets a leading'so spreadsheets show text instead of running a formula. JSON is left as stored. - Erased signups (tombstones) and removed signups are not included.
- The response is a download:
content-disposition: attachment,cache-control: no-store. A failure mid-stream aborts the connection, so a truncated file is detectable (a complete JSON export is a closed array).
DELETE /waitlists/:id/signups/:signupId — secret key
Erasure (personal-data request). 200 → the tombstone in the detail shape.
Safe to retry: a repeat returns the same tombstone with the original
deletedAt. See privacy.md.
PATCH /waitlists/:id/signups/:signupId — secret key
Moderation: body { "status": "removed" | "pending" } (strict; verified
cannot be set, only the person's own confirmation link verifies). 200 → the
detail shape.
| From | To | Result |
|---|---|---|
pending | removed | allowed |
verified | removed | allowed |
removed | pending | allowed (restore; confirms again, verifiedAt cleared) |
| same status | same | 200, nothing changes (safe to retry) |
| anything else | 409 illegal_transition |
Removed is not erased: the row, address and referral links stay, the signup
leaves the live ranking (everyone behind moves up one place) and the
leaderboard, and credit it earned its referrer is untouched. Erasure
(DELETE) is the only way to delete personal data. Other errors: 409
signup_erased (a tombstone cannot be changed), 409 signup_changed
(lost a race to a different change), 409 waitlist_archived (restore
needs an active waitlist), 402 plan_limit_reached (a restore counts as a
live signup), 404. Removed signups are listed with ?status=removed only.
POST /waitlists/:id/signups/:signupId/resend — secret key
Queues a fresh confirmation email (new token; earlier ones stay valid until
they expire). 202 → { "queued": true }. 409 if the signup is already
confirmed or the waitlist has double opt-in off; 404 for an unknown or erased
signup. Limited to 3 per signup per day (429).
GET /confirm?token= — no key
The link in the confirmation email. The token is 32 random bytes (base64url),
single use, valid 48 hours, and stored only as a SHA-256 hash. Always answers
303:
- valid (or already used):
Locationis the waitlist'sredirect_urlwhen it matches the allowlist, otherwise/confirmed. Opening the link again gives the same result and sends nothing new. - unknown, tampered, expired or malformed:
/confirmed?status=invalid.
The first valid use sets the signup to verified, stamps verifiedAt, and
queues the welcome email. Responses carry Referrer-Policy: no-referrer so
the token never reaches the redirect target.
POST /remove?token= — no key
The recipient's own "remove me", reached from the footer of every email
through the /remove page (which asks first, so mail scanners that prefetch
links erase nothing) and directly by mail clients' one-click unsubscribe
(RFC 8058: a form-encoded List-Unsubscribe=One-Click body, which is read and
ignored). Erases the signup like creator-initiated erasure
(privacy.md). The token is single-purpose, never expires, and a
replay gives the same result. Answers 303 to /removed (or
/removed?status=invalid). GET is not routed.
POST /unsubscribe?token= — no key
Switches off one kind of notification email (the signup digest, milestones,
plan limit, webhook failure, spam spike, billing or product update mails
GetWait sends to account owners). Reached from the footer of every such email
through the /unsubscribe page (which asks first) and directly by mail
clients' one-click unsubscribe (RFC 8058, form-encoded body ignored). The
token is signed, names one account and one category, never expires, and a
replay gives the same result. A bad or tampered token changes nothing. Answers
303 to /unsubscribed (or /unsubscribed?status=invalid). GET is not
routed. Limited like /remove: 30 per IP.
API keys and allowed origins
A publishable key is safe in the browser only because it is limited to the
origins you list. The list belongs to the project and applies to every
publishable key in it. Matching is exact string equality against the
request's Origin header: https://example.com does not admit
https://www.example.com, http://example.com or https://example.com:8443.
An entry is scheme://host[:port] with http/https, no path, no trailing
slash and no wildcard (*, https://*.example.com and null are rejected with
422). A project holds at most 20 origins.
An empty list admits any origin (or none, so curl works) in development and
refuses every request in production. A non-empty list also refuses requests with
no Origin header. Changes apply to the very next request.
All routes need a secret key and act on the caller's project only. The key itself is never returned; create and revoke keys in the dashboard.
GET /api-keys
200 → { keys: [{ id, kind, label, prefix, lastUsedAt, revokedAt, createdAt }] }, revoked keys included.
GET /project/origins
200 → { allowedOrigins }.
PUT /project/origins
Body { allowedOrigins: string[] } replaces the whole list; duplicates are
dropped. Idempotent.
POST /project/origins
Body { origin: string } adds one origin. Adding a listed origin changes
nothing, so a retry is safe.
DELETE /project/origins?origin=
Removes one origin (URL-encode the query value). Removing an unlisted origin changes nothing. Removing the last origin leaves an empty list, which production refuses for every request.
curl -X POST https://getwait.example/api/v1/project/origins \
-H "Authorization: Bearer $GETWAIT_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"origin":"https://app.example.com"}'
In the dashboard, the API keys tab shows the project's addresses as chips: use × to remove one and Add address to add one; Edit replaces the whole list.
Concurrent edits of the list resolve last-write-wins, as for waitlist settings.
Webhooks
Three events: signup.created, signup.verified, referral.converted.
All routes below are secret-key only and scoped to the key's project (another
project's endpoint or delivery is 404).
POST /webhook-endpoints
{
"url": "https://example.com/hooks/getwait",
"events": ["signup.created", "signup.verified"]
}
url:httpsonly (httpis accepted when the server runs withNODE_ENV=development). No credentials, no fragment, at most 2048 chars. Rejected with422: literal or named loopback, private, link-local and metadata addresses (including decimal, hex and octal IPv4 spellings and IPv4-mapped IPv6),localhost,*.local,*.internal, single-label hosts. The same check runs again at delivery time on the addresses the host name actually resolves to, so a name that later points at a private address is refused too. Redirects are never followed (a3xxcounts as a failed attempt).events: one or more of the three types; duplicates are dropped.- At most 10 endpoints per project (
409beyond that).
201 → { id, url, events, enabled, disabledAt, disabledReason, createdAt, secret }. secret (whsec_...) appears in this response only. It is
stored encrypted and no endpoint returns it again; to rotate it, call
POST /webhook-endpoints/:id/rotate-secret.
GET /webhook-endpoints, GET /webhook-endpoints/:id
Same shape without secret.
PATCH /webhook-endpoints/:id
Any of url, events, enabled (at least one). enabled: false records
disabledReason: "manual". enabled: true clears disabledAt,
disabledReason and the failure streak.
Endpoint objects also carry consecutiveFailures, autoDisabled (we switched
it off after 5 exhausted deliveries in a row) and previousSecretExpiresAt.
Re-enable an auto-disabled endpoint with enabled: true.
POST /webhook-endpoints/:id/rotate-secret
200 → the endpoint plus the new secret (shown once). For 24 hours the old
secret keeps signing too: each request then carries two values,
GetWait-Signature: t=...,v1=<new>,v1=<old>, and any matching v1 is
enough (the SDK and the documented verifiers already accept this). After
previousSecretExpiresAt only the new secret signs. Rotating again inside the
window replaces the old secret. Not idempotent.
POST /webhook-endpoints/:id/test
202 → a delivery of type webhook.test (data.message), signed and sent
through the normal drain and SSRF checks, attempted once; read the result in
the delivery log. It does not count toward auto-disabling. 409 if the
endpoint is disabled. Not subscribable.
DELETE /webhook-endpoints/:id
200 → { id, deleted: true }. Its deliveries are deleted with it.
Events
Every request body is the envelope
{
"id": "05e738f8-4da8-857e-9d19-891448412786",
"type": "signup.created",
"created_at": "2026-11-01T12:00:00.000Z",
"api_version": "2026-11-01",
"data": {
"signup": {
"id": "...",
"waitlist_id": "...",
"email": "...",
"status": "pending",
"referral_code": "...",
"referred_by_signup_id": null,
"verified_at": null,
"created_at": "..."
}
}
}
referral.converted carries
data.referral: { id, waitlist_id, referrer_signup_id, referred_signup_id }
and no email. The event id is derived from the event type and the signup
(or referral), so it is the same on every retry, every redelivery and every
duplicate trigger. Delivery is at-least-once: deduplicate on id. Order
across events is not guaranteed.
Events are written in the same database transaction as the change that caused them, to every enabled endpoint subscribed at that moment. Nothing is backfilled for an endpoint created or re-enabled later.
Request headers and verification
GetWait-Signature: t=1700000000,v1=<hex>
GetWait-Event-Id: <envelope id>
GetWait-Delivery-Attempt: 1
v1 is HMAC-SHA256(secret, t + "." + rawBody) as lowercase hex. Verify
against the raw bytes, before parsing the JSON, and reject timestamps more
than 5 minutes from your clock:
import { verifyWebhookSignature } from "@getwait/shared"
const result = await verifyWebhookSignature({
payload: rawBody,
header: request.headers.get("GetWait-Signature"),
secret: process.env.GETWAIT_WEBHOOK_SECRET!,
})
if (!result.ok) return new Response(null, { status: 400 })
The comparison is constant-time. Several v1= values may appear in one
header; any match is enough. Respond 2xx within 10 seconds.
Retries
Any 2xx is success. Anything else (other status, redirect, timeout,
connection or TLS error) is retried after 1 min, 5 min, 30 min, 2 h, 5 h,
8 h, 8 h (each +-20%), so 8 attempts over about 24 hours; then the delivery
is failed. After 5 consecutive deliveries fail that way, with no success in
between, the endpoint is disabled (disabledReason: "sustained_failure") and
an webhook_endpoint_disabled ops event is recorded. Enable it again with
PATCH. Deliveries still queued for a disabled endpoint are failed with
endpoint_disabled.
GET /webhook-endpoints/:id/deliveries
200 → { deliveries: [...] }, the newest 100:
{ id, eventId, eventType, status, attempts, nextAttemptAt, lastError, createdAt }. status is pending, delivered or failed; nextAttemptAt
is set only while pending. lastError is a short reason: http_<status>,
timeout, dns_error, connection_error, tls_error, blocked_address,
endpoint_disabled, signup_erased. The payload and the signing secret are
never included.
POST /webhook-endpoints/:id/deliveries/:deliveryId/redeliver
Re-queues a delivered or failed delivery (same row, same event id,
attempts reset) and answers 202 with its new state. 409 when the delivery
is already pending (delivery_pending), the endpoint is disabled
(endpoint_disabled) or the payload was erased (payload_erased).
Erasure
When a signup is erased (creator or recipient), its pending deliveries are
failed with signup_erased and every stored payload that names it has data
replaced by { "redacted": true }.
Plan limits
| Plan | Free projects per account | Waitlists per project | Live signups per waitlist | Emails |
|---|---|---|---|---|
| free | 2 | 2 | 1,000 | "Powered by GetWait" |
| paid | unlimited | unlimited | unlimited | no branding |
Projects start on the free plan, so the project limit counts an account's free-plan projects; upgrading a project frees a slot.
An unknown plan name is treated as paid. Billing is not built: plans are set
by hand (see docs/ops/plan-upgrade.md).
Going over a limit answers 402 with code plan_limit_reached:
{
"error": {
"code": "plan_limit_reached",
"message": "The free plan allows 1000 signups per waitlist",
"requestId": "...",
"details": {
"resource": "signups",
"limit": 1000,
"plan": "free",
"upgrade": "Upgrade your plan to remove this limit. Existing data is not affected."
}
}
}
POST /waitlistsis refused once the project owns 2 active waitlists; archived waitlists do not count. Restoring one (POST /waitlists/:id/restoreorPATCHwitharchived: false) is checked against the same limit.POST /waitlists/:id/signupsis refused once the waitlist has 1,000 live signups. Erased and removed signups do not count, so erasing frees a slot. Concurrent joins at the boundary are serialized, so the cap is never exceeded.- Nothing already stored is touched: existing signups keep their positions, a repeated join of an address already on the list still returns it (200), and confirm links of existing signups keep working.
Email limits
Each project may have a bounded number of emails scheduled per UTC day:
200 on the free plan, 2000 on paid plans (EMAIL_DAILY_CAP_FREE,
EMAIL_DAILY_CAP_PAID). Confirmation, welcome and resent emails each take one
slot, reserved atomically in the same transaction as the signup.
When a project is over its cap nothing fails: the signup is created, the
join response is unchanged, and the email is scheduled for the first following
UTC day with room (the confirm link is valid for 48 hours from when it is due
to be sent). If no day within 7 days has room, the email is not queued and the
signup stays pending; the creator can use resend later. An
email_cap_reached ops event is written once per project per day for a
deferral, and once more if emails are dropped.
Rate limits
Limits are shared across all server instances and counted per minute on a sliding approximation (the previous minute counts for the share that still overlaps). Every request counts, including rejected and invalid ones.
| Route | Limit |
|---|---|
POST /waitlists/:id/signups | 10 per IP, and 3 per (IP, email) |
GET /waitlists/:id/signups/by-code/:referralCode | 30 per IP |
GET /confirm, POST /remove, POST /unsubscribe | 30 per IP |
POST /waitlists/:id/signups/:signupId/resend | 600 per API key, 3 per signup per day |
GET /waitlists/:id/export | 5 per hour per API key |
| every other keyed route | 600 per API key |
Responses on limited routes carry RateLimit-Limit, RateLimit-Remaining
and RateLimit-Reset (seconds until the window ends) for the rule closest to
its limit. When exceeded the API answers 429 with code rate_limited, the
usual error envelope, and Retry-After in seconds. Browser clients can read
all of these headers.
If the limiter's own storage is down, join and by-code answer 503 with
code rate_limiter_unavailable and Retry-After; the keyed routes keep
working unlimited. See docs/adr/0002-rate-limiter-failure-modes.md.
The client IP comes from the header named by TRUSTED_IP_HEADER (default
x-real-ip), never from a client-supplied X-Forwarded-For. IPv6 clients
are limited per /64.