API reference

Waitlist API.

Public signup endpoints anyone can hit from a frontend, plus the admin endpoints that drive the console. Every endpoint generated from the live OpenAPI spec.

Waitlist exposes two surfaces. The public surface under /v1/waitlists/{workspace_slug}/{waitlist_slug} needs no auth: your own frontend reads the waitlist config with GET and posts signups to POST .../entries. There is no hosted signup page — you render the form. The admin surface under /v1/workspaces/{workspace_id}/... needs a bearer token (platform session or pcft_live_* key) and covers waitlists, entries, variants, analytics, and webhooks. Both are documented below.

Base URL

https://api.waitlist.productcraft.co

Auth

Authorization: Bearer …

Spec version

OpenAPI 3.0.0 · v0.1.0

OpenAPI spec

https://api.waitlist.productcraft.co/docs-json

Waitlist-Settings

get/v1/workspaces/{workspace_id}/waitlist/settingsAuth

Read workspace-level Waitlist defaults

Path parameters

workspace_id*string

Response · 200 Workspace Waitlist settings.

workspace_id*string · uuid

default_sender_domain_id*string · uuid

Mail domain UUID used as default sender for Waitlist notifications.

default_heimdall_app_slug*string

Auth consumer-app slug approved entries are invited into.

brand_name*string

brand_logo_url*string

primary_color*string

Primary brand colour as #RRGGBB

notifications_via_envoi*boolean

Whether Waitlist notifications are routed through the Mail service.

default_sender_address*string

welcome_template_name*string

approved_template_name*string

rejected_template_name*string

updated_at*string · date-time

null when the workspace has no explicit settings row yet.

Example

Request

GET /v1/workspaces/{workspace_id}/waitlist/settings
Authorization: Bearer YOUR_TOKEN

Response

{
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "default_sender_domain_id": "00000000-0000-0000-0000-000000000000",
  "default_heimdall_app_slug": "string",
  "brand_name": "string",
  "brand_logo_url": "string",
  "primary_color": "string",
  "notifications_via_envoi": false,
  "default_sender_address": "string",
  "welcome_template_name": "string",
  "approved_template_name": "string",
  "rejected_template_name": "string",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

put/v1/workspaces/{workspace_id}/waitlist/settingsAuth

Update workspace-level Waitlist defaults

Path parameters

workspace_id*string

Request body

default_sender_domain_idstring

Mail domain UUID to use as default sender for Waitlist notifications. null clears the override.

default_heimdall_app_slugstring

Auth consumer-app slug to invite approved entries into. null clears the link.

brand_namestring

Brand name returned in the public waitlist payload. Customer frontends render it on their own signup form.

brand_logo_urlstring

Logo URL returned in the public waitlist payload. Customer frontends render it on their own signup form.

primary_colorstring

Primary brand colour as #RRGGBB

notifications_via_envoiboolean

Route Waitlist notifications through the Mail service (workspace sender domain + per-event template selection) instead of staying silent. Requires default_sender_domain_id, default_sender_address, and a template name for every supported event. Default false; when off, Waitlist sends no notification emails and the customer is expected to handle email via the webhook lane.

default_sender_addressstring

Verified sender address used as the From envelope on Waitlist notifications. Must belong to default_sender_domain_id. null clears the override.

welcome_template_namestring

Mail template name used for entry.created notifications. Must already exist in the workspace template store.

approved_template_namestring

Mail template name used for entry.approved notifications. Must already exist in the workspace template store.

rejected_template_namestring

Mail template name used for entry.rejected notifications. Must already exist in the workspace template store.

Response · 200 Updated workspace Waitlist settings.

workspace_id*string · uuid

default_sender_domain_id*string · uuid

Mail domain UUID used as default sender for Waitlist notifications.

default_heimdall_app_slug*string

Auth consumer-app slug approved entries are invited into.

brand_name*string

brand_logo_url*string

primary_color*string

Primary brand colour as #RRGGBB

notifications_via_envoi*boolean

Whether Waitlist notifications are routed through the Mail service.

default_sender_address*string

welcome_template_name*string

approved_template_name*string

rejected_template_name*string

updated_at*string · date-time

null when the workspace has no explicit settings row yet.

Example

Request

PUT /v1/workspaces/{workspace_id}/waitlist/settings
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "default_sender_domain_id": "string",
  "default_heimdall_app_slug": "string",
  "brand_name": "string",
  "brand_logo_url": "string",
  "primary_color": "string",
  "notifications_via_envoi": false,
  "default_sender_address": "string",
  "welcome_template_name": "string",
  "approved_template_name": "string",
  "rejected_template_name": "string"
}

Response

{
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "default_sender_domain_id": "00000000-0000-0000-0000-000000000000",
  "default_heimdall_app_slug": "string",
  "brand_name": "string",
  "brand_logo_url": "string",
  "primary_color": "string",
  "notifications_via_envoi": false,
  "default_sender_address": "string",
  "welcome_template_name": "string",
  "approved_template_name": "string",
  "rejected_template_name": "string",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Waitlists

get/v1/workspaces/{workspace_id}/waitlistsAuth

List waitlists in this workspace

Path parameters

workspace_id*string · uuid

Query parameters

limitnumber

cursorstring

Opaque cursor for pagination

statusstring

Filter by status

Response · 200 Page of waitlists.

data*array

pagination*object

next_cursor*string

has_more*boolean

Example

Request

GET /v1/workspaces/{workspace_id}/waitlists
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "b1a4...",
      "workspace_id": "b1a4...",
      "workspace_slug": "acme",
      "slug": "early-access",
      "display_name": "Early Access Program",
      "description": "string",
      "status": "draft",
      "settings": {},
      "created_by": "string",
      "previous_workspace_slug": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "pagination": {
    "next_cursor": "string",
    "has_more": false
  }
}

post/v1/workspaces/{workspace_id}/waitlistsAuth

Create a waitlist (workspace-scoped)

Path parameters

workspace_id*string · uuid

Headers

Idempotency-Keystring

Stripe-style idempotency key. Waitlist creation provisions a non-trivial sub-tree (variant, default referral settings, etc.); a retry without this header creates a second waitlist sharing the same name slug. 24h TTL.

Request body

slug*string

URL-safe slug

Example: "early-access"

display_name*string

Display name

Example: "Early Access Program"

descriptionstring

Description returned in the public waitlist payload — customer frontends typically render it under the display name on their signup form.

settingsobject

Waitlist settings (max_entries, approval_required, custom_fields, confirmation_message, referral_boost)

Response · 201 Waitlist created.

id*string

Example: "b1a4..."

workspace_id*string

Example: "b1a4..."

workspace_slug*string

Example: "acme"

slug*string

Example: "early-access"

display_name*string

Example: "Early Access Program"

description*string

status*enum (4)

settings*object

Waitlist settings (max_entries, approval_required, custom_fields, confirmation_message, referral_boost).

created_by*string

previous_workspace_slug*string

created_at*string

updated_at*string

Example

Request

POST /v1/workspaces/{workspace_id}/waitlists
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "slug": "early-access",
  "display_name": "Early Access Program",
  "description": "string",
  "settings": {}
}

Response

{
  "id": "b1a4...",
  "workspace_id": "b1a4...",
  "workspace_slug": "acme",
  "slug": "early-access",
  "display_name": "Early Access Program",
  "description": "string",
  "status": "draft",
  "settings": {},
  "created_by": "string",
  "previous_workspace_slug": "string",
  "created_at": "string",
  "updated_at": "string"
}

get/v1/workspaces/{workspace_id}/waitlists/{id}Auth

Get waitlist details

Path parameters

id*string

workspace_id*string · uuid

Response · 200 Waitlist row.

id*string

Example: "b1a4..."

workspace_id*string

Example: "b1a4..."

workspace_slug*string

Example: "acme"

slug*string

Example: "early-access"

display_name*string

Example: "Early Access Program"

description*string

status*enum (4)

settings*object

Waitlist settings (max_entries, approval_required, custom_fields, confirmation_message, referral_boost).

created_by*string

previous_workspace_slug*string

created_at*string

updated_at*string

Example

Request

GET /v1/workspaces/{workspace_id}/waitlists/{id}
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "b1a4...",
  "workspace_id": "b1a4...",
  "workspace_slug": "acme",
  "slug": "early-access",
  "display_name": "Early Access Program",
  "description": "string",
  "status": "draft",
  "settings": {},
  "created_by": "string",
  "previous_workspace_slug": "string",
  "created_at": "string",
  "updated_at": "string"
}

patch/v1/workspaces/{workspace_id}/waitlists/{id}Auth

Update waitlist metadata and settings

Path parameters

id*string

workspace_id*string · uuid

Request body

display_namestring

New display name

descriptionstring

New description

settingsobject

Updated settings (merged shallow)

Response · 200 Waitlist updated.

id*string

Example: "b1a4..."

workspace_id*string

Example: "b1a4..."

workspace_slug*string

Example: "acme"

slug*string

Example: "early-access"

display_name*string

Example: "Early Access Program"

description*string

status*enum (4)

settings*object

Waitlist settings (max_entries, approval_required, custom_fields, confirmation_message, referral_boost).

created_by*string

previous_workspace_slug*string

created_at*string

updated_at*string

Example

Request

PATCH /v1/workspaces/{workspace_id}/waitlists/{id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "display_name": "string",
  "description": "string",
  "settings": {}
}

Response

{
  "id": "b1a4...",
  "workspace_id": "b1a4...",
  "workspace_slug": "acme",
  "slug": "early-access",
  "display_name": "Early Access Program",
  "description": "string",
  "status": "draft",
  "settings": {},
  "created_by": "string",
  "previous_workspace_slug": "string",
  "created_at": "string",
  "updated_at": "string"
}

delete/v1/workspaces/{workspace_id}/waitlists/{id}Auth

Delete a waitlist (cascades to entries)

Path parameters

id*string

workspace_id*string · uuid

Response · 204

Waitlist deleted.

patch/v1/workspaces/{workspace_id}/waitlists/{id}/statusAuth

Change waitlist status

Path parameters

id*string

workspace_id*string · uuid

Request body

status*enum (4)

New status

Response · 200 Status updated.

id*string

Example: "b1a4..."

workspace_id*string

Example: "b1a4..."

workspace_slug*string

Example: "acme"

slug*string

Example: "early-access"

display_name*string

Example: "Early Access Program"

description*string

status*enum (4)

settings*object

Waitlist settings (max_entries, approval_required, custom_fields, confirmation_message, referral_boost).

created_by*string

previous_workspace_slug*string

created_at*string

updated_at*string

Example

Request

PATCH /v1/workspaces/{workspace_id}/waitlists/{id}/status
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "status": "draft"
}

Response

{
  "id": "b1a4...",
  "workspace_id": "b1a4...",
  "workspace_slug": "acme",
  "slug": "early-access",
  "display_name": "Early Access Program",
  "description": "string",
  "status": "draft",
  "settings": {},
  "created_by": "string",
  "previous_workspace_slug": "string",
  "created_at": "string",
  "updated_at": "string"
}

Entries

get/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entriesAuth

List entries on a waitlist (paginated)

Path parameters

workspace_id*string

waitlist_id*string

Query parameters

limitnumber

cursorstring

Opaque cursor for pagination

statusstring

Filter by status

Response · 200 Page of entries with pagination cursor.

data*array

pagination*object

next_cursor*string

has_more*boolean

Example

Request

GET /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "string",
      "waitlist_id": "string",
      "workspace_id": "string",
      "email": "string",
      "name": "string",
      "interest": "string",
      "referrer": "string",
      "referral_code": "string",
      "referral_count": 0,
      "referred_by_entry_id": "string",
      "position": 0,
      "status": "pending",
      "invited_at": "string",
      "invited_to_app_slug": "string",
      "metadata": {},
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "pagination": {
    "next_cursor": "string",
    "has_more": false
  }
}

get/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/countAuth

Total entry count for a waitlist

Path parameters

workspace_id*string

waitlist_id*string

Response · 200 Total entry count.

count*number

Total number of entries on the waitlist.

Example

Request

GET /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/count
Authorization: Bearer YOUR_TOKEN

Response

{
  "count": 0
}

get/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/export.csvAuth

Stream every entry as CSV (admin export)

Path parameters

workspace_id*string

waitlist_id*string

Response · 200

text/csv stream — one header row + one row per entry. Content-Disposition: attachment.

get/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/{entry_id}Auth

Get a single entry

Path parameters

workspace_id*string

waitlist_id*string

entry_id*string

Response · 200 Entry row.

id*string

waitlist_id*string

workspace_id*string

email*string

name*string

interest*string

referrer*string

referral_code*string

referral_count*number

referred_by_entry_id*string

position*number

status*enum (3)

invited_at*string

invited_to_app_slug*string

metadata*object

created_at*string

updated_at*string

Example

Request

GET /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/{entry_id}
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "string",
  "waitlist_id": "string",
  "workspace_id": "string",
  "email": "string",
  "name": "string",
  "interest": "string",
  "referrer": "string",
  "referral_code": "string",
  "referral_count": 0,
  "referred_by_entry_id": "string",
  "position": 0,
  "status": "pending",
  "invited_at": "string",
  "invited_to_app_slug": "string",
  "metadata": {},
  "created_at": "string",
  "updated_at": "string"
}

patch/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/{entry_id}Auth

Approve or reject an entry

Path parameters

workspace_id*string

waitlist_id*string

entry_id*string

Request body

status*enum (2)

Target status

Response · 200 Entry status updated.

id*string

waitlist_id*string

workspace_id*string

email*string

name*string

interest*string

referrer*string

referral_code*string

referral_count*number

referred_by_entry_id*string

position*number

status*enum (3)

invited_at*string

invited_to_app_slug*string

metadata*object

created_at*string

updated_at*string

Example

Request

PATCH /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/{entry_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "status": "approved"
}

Response

{
  "id": "string",
  "waitlist_id": "string",
  "workspace_id": "string",
  "email": "string",
  "name": "string",
  "interest": "string",
  "referrer": "string",
  "referral_code": "string",
  "referral_count": 0,
  "referred_by_entry_id": "string",
  "position": 0,
  "status": "pending",
  "invited_at": "string",
  "invited_to_app_slug": "string",
  "metadata": {},
  "created_at": "string",
  "updated_at": "string"
}

delete/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/{entry_id}Auth

Delete an entry (positions are not renumbered)

Path parameters

workspace_id*string

waitlist_id*string

entry_id*string

Response · 204

Entry deleted.

post/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/{entry_id}/invite-to-appAuth

Invite an approved entry into a linked Auth consumer app (one-click cross-product handoff)

Path parameters

workspace_id*string

waitlist_id*string

entry_id*string

Request body

app_slugstring

Auth app slug to invite into; defaults to the workspace Waitlist settings default (`default_heimdall_app_slug`)

send_emailboolean

Send the approval email with the Auth invite link baked in

Response · 200 Invite created in Auth

entry*object

The entry row after `invited_at` / `invited_to_app_slug` were stamped.

invite_id*string

Auth invite id created in the linked app.

invite_urlstring

Invite acceptance URL, when the Auth app returned one. Baked into the approval email when send_email is enabled.

Example

Request

POST /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/{entry_id}/invite-to-app
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "app_slug": "string",
  "send_email": false
}

Response

{
  "entry": {},
  "invite_id": "string",
  "invite_url": "string"
}

post/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/bulkAuth

Bulk-apply approve / reject / invite-to-app to multiple entries at once. Capped at 100 ids per call. Processed serially server-side; per-row results are returned so the UI can render partial successes.

Path parameters

workspace_id*string

waitlist_id*string

Request body

ids*array

Entry UUIDs to act on in this batch. Capped at 100 per call; the request is processed serially and per-row results are returned. De-duped server-side.

Example: ["11111111-1111-1111-1111-111111111111","22222222-2222-2222-2222-222222222222"]

action*enum (3)

Action to apply to every id.

Example: "approve"

app_slugstring

Auth app slug override for `action: invite-to-app`. When omitted, falls back to the workspace Waitlist settings default (`default_heimdall_app_slug`). Ignored for approve/reject.

Example: "acme-product"

send_emailboolean

Whether to send the approval email with the invite link baked in. Defaults to `true`. Ignored for approve/reject.

Response · 200 `{ requested, succeeded, failed, results }`. Each row in `results` carries `{ id, status: "ok" | "error", error?: { code, message } }` so a partial failure (one bad id) doesn't fail the whole batch.

requested*number

Number of unique ids processed (after de-dupe).

succeeded*number

failed*number

results*array

Example

Request

POST /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/bulk
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "ids": [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ],
  "action": "approve",
  "app_slug": "acme-product",
  "send_email": false
}

Response

{
  "requested": 0,
  "succeeded": 0,
  "failed": 0,
  "results": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status": "ok",
      "error": {
        "code": 0,
        "message": "string"
      }
    }
  ]
}

Public-Waitlist

get/v1/waitlists/{workspace_slug}/{waitlist_slug}

Public waitlist info (display name, description, custom-field schema, branding hints, active variant)

Path parameters

workspace_slug*string

waitlist_slug*string

Query parameters

langstring

BCP-47 locale tag (e.g. `en`, `pt-BR`). Wins over Accept-Language when picking the variant.

Response · 200 Public waitlist info

slug*string

Waitlist slug.

workspace_slug*string

Workspace slug the request resolved against.

canonical_workspace_slug*string

Canonical workspace slug. When the request URL used a stale slug, compare with the URL slug and 301-redirect.

display_name*string

Display name (active variant copy wins over the stored name).

description*string

status*string

Always `active` — non-active waitlists return 404.

custom_fields*array

confirmation_message*string

Message to show after a successful signup.

recaptcha_site_key*string

reCAPTCHA v3 site key. When non-null, POST .../entries requires a `recaptcha_token`.

referral_rewards*object

milestones*array

Milestones sorted by count, ascending. Empty when the waitlist has no referral rewards configured.

variant*object

Active A/B or locale variant served for this request; null when none configured.

brand*object

brand_name*string

brand_logo_url*string

primary_color*string

Primary brand colour as #RRGGBB.

Example

Request

GET /v1/waitlists/{workspace_slug}/{waitlist_slug}

Response

{
  "slug": "string",
  "workspace_slug": "string",
  "canonical_workspace_slug": "string",
  "display_name": "string",
  "description": "string",
  "status": "string",
  "custom_fields": [
    {
      "key": "string",
      "label": "string",
      "type": "string",
      "required": false,
      "options": [
        "string"
      ]
    }
  ],
  "confirmation_message": "string",
  "recaptcha_site_key": "string",
  "referral_rewards": {
    "milestones": [
      {
        "count": 0,
        "reward": "string"
      }
    ]
  },
  "variant": {},
  "brand": {
    "brand_name": "string",
    "brand_logo_url": "string",
    "primary_color": "string"
  }
}

get/v1/waitlists/{workspace_slug}/{waitlist_slug}/leaderboard

Public top-50 referral leaderboard. Emails are masked. Anonymous read; same access policy as the public waitlist info endpoint.

Path parameters

workspace_slug*string

waitlist_slug*string

Query parameters

limitstring

Number of rows (1-50, default 50)

Response · 200 Array of `{ position, referral_count, masked_email }`

Array of object

position*number

Signup position on the waitlist.

referral_count*number

Number of honoured referrals.

masked_email*string

Masked email, e.g. `a***@example.com`.

Example: "a***@example.com"

Example

Request

GET /v1/waitlists/{workspace_slug}/{waitlist_slug}/leaderboard

Response

[
  {
    "position": 0,
    "referral_count": 0,
    "masked_email": "a***@example.com"
  }
]

post/v1/waitlists/{workspace_slug}/{waitlist_slug}/entries

Submit a new entry to a public waitlist

Path parameters

workspace_slug*string

waitlist_slug*string

Request body

email*string

Email address

Example: "ada@example.com"

name*string

Full name

Example: "Ada Lovelace"

intereststring

Free-text product interest

referrerstring

How they heard about it

referral_codestring

Referral code from a prior signup; bumps that signup’s position when honoured

metadataobject

Custom field values

recaptcha_tokenstring

reCAPTCHA v3 token; verified server-side when the waitlist has settings.recaptcha_site_key

variant_idstring · uuid

Variant id this submission was attributed to. Customer frontends fetch the active variant from `GET /v1/waitlists/:workspaceSlug/:waitlistSlug` and round-trip it here on POST so per-variant conversion can be computed without a separate impressions table.

Response · 201 Entry created. Persist `referral_code` client-side to build the referral URL; `status` is `approved` when the waitlist auto-approves.

id*string · uuid

Entry id.

email*string

Normalised (lower-cased) email.

name*string

position*number

Immutable signup position (1-based order of signup).

status*enum (2)

`approved` when the waitlist auto-approves; `pending` when admin approval is required.

referral_code*string

Referral code for this signup. Build your referral URL from it and pass it as `referral_code` on subsequent signups.

created_at*string · date-time

effective_position*number

Visible position after applying the referral boost — "you would be #N if approved now". Equals `position` at signup time (no referrals yet).

Example

Request

POST /v1/waitlists/{workspace_slug}/{waitlist_slug}/entries
Content-Type: application/json

{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "interest": "string",
  "referrer": "string",
  "referral_code": "string",
  "metadata": {},
  "recaptcha_token": "string",
  "variant_id": "00000000-0000-0000-0000-000000000000"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "email": "string",
  "name": "string",
  "position": 0,
  "status": "pending",
  "referral_code": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "effective_position": 0
}

Analytics

get/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/analyticsAuth

Aggregate counts, viral coefficient, top referrers + referrals

Path parameters

workspace_id*string

waitlist_id*string

Response · 200 Aggregated analytics payload for the waitlist.

waitlist_id*string · uuid

total_entries*number

by_status*object

Entry counts keyed by status (`pending` / `approved` / `rejected`).

Example: {"pending":12,"approved":40,"rejected":3}

signups_today*number

signups_this_week*number

signups_this_month*number

viral_coefficient*number

referrals / total_entries — the K-factor proxy. 0 when no entries.

referred_count*number

top_referrers*array

top_referrals*array

Example

Request

GET /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/analytics
Authorization: Bearer YOUR_TOKEN

Response

{
  "waitlist_id": "00000000-0000-0000-0000-000000000000",
  "total_entries": 0,
  "by_status": {
    "pending": 12,
    "approved": 40,
    "rejected": 3
  },
  "signups_today": 0,
  "signups_this_week": 0,
  "signups_this_month": 0,
  "viral_coefficient": 0,
  "referred_count": 0,
  "top_referrers": [
    {
      "referrer": "string",
      "count": 0
    }
  ],
  "top_referrals": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "string",
      "name": "string",
      "referral_code": "string",
      "referral_count": 0,
      "position": 0,
      "effective_position": 0
    }
  ]
}

get/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/analytics/timelineAuth

Daily-bucketed signup timeline (UTC, dense — zero-count days included)

Path parameters

workspace_id*string

waitlist_id*string

Query parameters

since*string

ISO-8601 inclusive start

until*string

ISO-8601 exclusive end

Response · 200 Daily timeline array, oldest first, zero-count days included.

granularity*enum (1)

points*array

Oldest first; every day in [since, until) is present.

Example

Request

GET /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/analytics/timeline
Authorization: Bearer YOUR_TOKEN

Response

{
  "granularity": "day",
  "points": [
    {
      "date": "2026-08-01",
      "count": 0
    }
  ]
}

Waitlist-Variants

get/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variantsAuth

List all variants on a waitlist

Path parameters

workspace_id*string

waitlist_id*string

Response · 200 Bare array of variants

data*array

Example

Request

GET /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variants
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "string",
      "waitlist_id": "string",
      "kind": "ab",
      "locale": "string",
      "copy": {},
      "weight": 0,
      "active": false,
      "created_at": "string"
    }
  ]
}

post/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variantsAuth

Create a variant

Path parameters

workspace_id*string

waitlist_id*string

Request body

kind*enum (2)

locale*string

BCP-47 locale tag. For ab variants this is the locale they target; for locale variants this is the locale they serve. Case is normalised on the public side.

Example: "en"

copy*object

Copy overrides. Recognised keys: display_name, description, confirmation_message. Unknown keys are dropped on the public render.

weightnumber

Relative weight inside the ab pool. Ignored when kind=locale. Default 1.

activeboolean

Response · 201 Variant created

id*string

waitlist_id*string

kind*enum (2)

locale*string

copy*object

weight*number

active*boolean

created_at*string

Example

Request

POST /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variants
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "kind": "ab",
  "locale": "en",
  "copy": {},
  "weight": 0,
  "active": false
}

Response

{
  "id": "string",
  "waitlist_id": "string",
  "kind": "ab",
  "locale": "string",
  "copy": {},
  "weight": 0,
  "active": false,
  "created_at": "string"
}

patch/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variants/{id}Auth

Update a variant (locale, copy, weight, active)

Path parameters

workspace_id*string

waitlist_id*string

id*string

Request body

localestring

copyobject

display_namestring

descriptionstring

confirmation_messagestring

weightnumber

activeboolean

Response · 200 Variant updated

id*string

waitlist_id*string

kind*enum (2)

locale*string

copy*object

weight*number

active*boolean

created_at*string

Example

Request

PATCH /v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variants/{id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "locale": "string",
  "copy": {
    "display_name": "string",
    "description": "string",
    "confirmation_message": "string"
  },
  "weight": 0,
  "active": false
}

Response

{
  "id": "string",
  "waitlist_id": "string",
  "kind": "ab",
  "locale": "string",
  "copy": {},
  "weight": 0,
  "active": false,
  "created_at": "string"
}

delete/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variants/{id}Auth

Delete a variant

Path parameters

workspace_id*string

waitlist_id*string

id*string

Response · 204

Variant deleted

Webhooks

get/v1/workspaces/{workspace_id}/webhooksAuth

List webhooks for the workspace (secrets masked)

Path parameters

workspace_id*string

Response · 200 Webhooks for the workspace.

data*array

Example

Request

GET /v1/workspaces/{workspace_id}/webhooks
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "string",
      "workspace_id": "string",
      "url": "string",
      "events": [
        "entry.created"
      ],
      "active": false,
      "failure_count": 0,
      "last_status_code": 0,
      "last_attempt_at": "string",
      "auto_disabled_at": "string",
      "first_failure_at": "string",
      "created_at": "string"
    }
  ]
}

post/v1/workspaces/{workspace_id}/webhooksAuth

Create a workspace webhook. The response includes the per-row signing secret in clear EXACTLY ONCE — copy it now.

Path parameters

workspace_id*string

Headers

Idempotency-Keystring

Stripe-style idempotency key. The signing secret is returned exactly once; a retry without this header creates a second webhook + secret you never see the plaintext for. 24h TTL.

Request body

url*string

Destination URL (must be https in prod)

events*array

Events to subscribe to

Example: ["entry.created","entry.approved"]

activeboolean

Disabled webhooks store events but never deliver

Response · 201 Webhook created. Includes plaintext `signing_secret` exactly once.

id*string

workspace_id*string

url*string

events*array

active*boolean

failure_count*number

last_status_code*number

last_attempt_at*string

auto_disabled_at*string

first_failure_at*string

created_at*string

signing_secret*string

Plaintext signing secret returned EXACTLY ONCE on create + rotate. Persist immediately — it does not appear on subsequent GETs.

Example

Request

POST /v1/workspaces/{workspace_id}/webhooks
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "url": "string",
  "events": [
    "entry.created",
    "entry.approved"
  ],
  "active": false
}

Response

{
  "id": "string",
  "workspace_id": "string",
  "url": "string",
  "events": [
    "entry.created"
  ],
  "active": false,
  "failure_count": 0,
  "last_status_code": 0,
  "last_attempt_at": "string",
  "auto_disabled_at": "string",
  "first_failure_at": "string",
  "created_at": "string",
  "signing_secret": "string"
}

get/v1/workspaces/{workspace_id}/webhooks/{id}Auth

Get a webhook (secret masked)

Path parameters

workspace_id*string

id*string

Response · 200 Webhook row.

id*string

workspace_id*string

url*string

events*array

active*boolean

failure_count*number

last_status_code*number

last_attempt_at*string

auto_disabled_at*string

first_failure_at*string

created_at*string

Example

Request

GET /v1/workspaces/{workspace_id}/webhooks/{id}
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "string",
  "workspace_id": "string",
  "url": "string",
  "events": [
    "entry.created"
  ],
  "active": false,
  "failure_count": 0,
  "last_status_code": 0,
  "last_attempt_at": "string",
  "auto_disabled_at": "string",
  "first_failure_at": "string",
  "created_at": "string"
}

patch/v1/workspaces/{workspace_id}/webhooks/{id}Auth

Update url / events / active flag

Path parameters

workspace_id*string

id*string

Request body

urlstring

New URL

eventsarray

New event subscription

activeboolean

Pause/resume the webhook

Response · 200 Updated webhook row (secret masked).

id*string

workspace_id*string

url*string

events*array

active*boolean

failure_count*number

last_status_code*number

last_attempt_at*string

auto_disabled_at*string

first_failure_at*string

created_at*string

Example

Request

PATCH /v1/workspaces/{workspace_id}/webhooks/{id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "url": "string",
  "events": [
    "entry.created"
  ],
  "active": false
}

Response

{
  "id": "string",
  "workspace_id": "string",
  "url": "string",
  "events": [
    "entry.created"
  ],
  "active": false,
  "failure_count": 0,
  "last_status_code": 0,
  "last_attempt_at": "string",
  "auto_disabled_at": "string",
  "first_failure_at": "string",
  "created_at": "string"
}

delete/v1/workspaces/{workspace_id}/webhooks/{id}Auth

Delete a webhook

Path parameters

workspace_id*string

id*string

Response · 204

No content.

get/v1/workspaces/{workspace_id}/webhooks/{id}/deliveriesAuth

Recent delivery attempts for a webhook (default 50, max 200, newest first)

Path parameters

workspace_id*string

id*string

Response · 200 `{ data: Array<{ id, webhook_id, event_id, event_type, attempt_number, status_code, response_body_truncated, error_message, latency_ms, attempted_at }> }`, newest first.

data*array

Example

Request

GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "webhook_id": "00000000-0000-0000-0000-000000000000",
      "event_id": "string",
      "event_type": "entry.created",
      "attempt_number": 0,
      "status_code": 0,
      "response_body_truncated": "string",
      "error_message": "string",
      "latency_ms": 0,
      "attempted_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

post/v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secretAuth

Rotate the signing secret. Returns the new secret in clear EXACTLY ONCE.

Path parameters

workspace_id*string

id*string

Response · 201 Secret rotated. Includes the new plaintext secret exactly once.

id*string · uuid

secret*string

New plaintext signing secret, returned EXACTLY ONCE. Persist immediately — it does not appear on subsequent GETs.

Example

Request

POST /v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "secret": "string"
}

post/v1/workspaces/{workspace_id}/webhooks/{id}/testAuth

Fire a synthetic test event to this webhook (asynchronous; check the destination logs)

Path parameters

workspace_id*string

id*string

Request body

event*enum (3)

Event type to fire as a synthetic test

waitlist_idstring

Waitlist UUID to reference in the synthetic payload. Defaults to a placeholder UUID when omitted.

Response · 202

No content.

Example

Request

POST /v1/workspaces/{workspace_id}/webhooks/{id}/test
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "event": "entry.created",
  "waitlist_id": "string"
}