API Reference — PreLaunch Waitlist

Waitlist

POST /waitlist/subscribe Public

Add an email address to a project's waitlist. Duplicate entries are silently deduplicated. This endpoint is called automatically by the browser SDK.

Request body

Field	Type	Required	Description
`projectId`	string	Required	The ID of the project to subscribe to.
`email`	string	Required	The subscriber's email address.
`metadata`	object	Optional	Arbitrary key/value pairs to attach to the subscriber record.
`utm`	object	Optional	UTM parameters (e.g. `utm_source`, `utm_campaign`).
`referrer`	string	Optional	The page referrer URL.
`formData`	object	Optional	Additional form fields captured alongside the email. Accepts flat string key/value pairs only. Capped at 30 fields; keys ≤ 100 chars; values ≤ 1 000 chars.

Request

{
  "projectId": "abc123",
  "email": "[email protected]",
  "metadata": { "plan": "pro" },
  "utm": { "utm_source": "twitter" }
}

Response 201

{ "success": true }

GET /waitlist/{projectId} Auth required

Return all subscribers for a project, ordered by sign-up date descending.

Path parameters

Parameter	Description
`projectId`	The project's unique ID.

Response 200

{
  "subscribers": [
    {
      "id": "[email protected]",
      "email": "[email protected]",
      "subscribedAt": "2026-04-10T14:32:00.000Z",
      "metadata": {}
    }
  ]
}

Projects

A project maps to a single waitlist. Each authenticated user can own multiple projects.

POST /projects Auth required

Create a new project.

Request body

Field	Type	Required	Description
`name`	string	Required	Display name for the project.
`description`	string	Optional	Short description shown in the dashboard.

Request

{
  "name": "My Product Waitlist",
  "description": "Early-access list for v2 launch"
}

Response 201

{ "id": "abc123", "name": "My Product Waitlist" }

GET /projects Auth required

List all projects owned by the authenticated user, ordered by creation date descending.

Response 200

{
  "projects": [
    {
      "id": "abc123",
      "name": "My Product Waitlist",
      "description": "Early-access list for v2 launch",
      "subscriberCount": 142,
      "webhookEnabled": true,
      "slackEnabled": false,
      "createdAt": "2026-04-01T09:00:00.000Z"
    }
  ]
}

Webhooks

Register HTTP endpoints to receive real-time notifications when subscribers join your waitlist. See the Webhook documentation for payload format, signature verification, and integration examples.

POST /webhooks/{projectId} Auth required

Register a new webhook URL for a project. Returns the webhook ID and a signing secret — store the secret securely; it is not shown again.

Request body

Field	Type	Required	Description
`url`	string	Required	The HTTPS URL to deliver payloads to.
`events`	string[]	Optional	Event types to subscribe to. Defaults to `["subscriber.created"]`. Currently the only supported event is `subscriber.created`.

Request

{
  "url": "https://yourserver.com/plw-hook",
  "events": ["subscriber.created"]
}

Response 201

{
  "id": "wh_xyz789",
  "url": "https://yourserver.com/plw-hook",
  "events": ["subscriber.created"],
  "secret": "a3f8...c1d2"
}

GET /webhooks/{projectId} Auth required

List all webhooks registered for a project.

Response 200

{
  "webhooks": [
    {
      "id": "wh_xyz789",
      "url": "https://yourserver.com/plw-hook",
      "events": ["subscriber.created"],
      "active": true,
      "createdAt": "2026-04-10T12:00:00.000Z"
    }
  ]
}

DELETE /webhooks/{projectId}/{webhookId} Auth required

Remove a webhook. Delivery stops immediately.

Response 200

{ "success": true }

Slack integration

Connect a Slack Incoming Webhook URL to get a channel message for every new subscriber. Only one Slack integration per project is supported.

POST /slack/{projectId} Auth required

Save or replace the Slack Incoming Webhook URL for a project. The integration is enabled immediately.

Request body

Field	Type	Required	Description
`webhookUrl`	string	Required	A valid Slack Incoming Webhook HTTPS URL.
`label`	string	Optional	A friendly label for the integration, shown in the dashboard.

Request

{
  "webhookUrl": "https://hooks.slack.com/services/T.../B.../...",
  "label": "#waitlist-alerts"
}

Response 200

{
  "webhookUrl": "https://hooks.slack.com/services/...",
  "label": "#waitlist-alerts",
  "active": true
}

GET /slack/{projectId} Auth required

Retrieve the current Slack integration config for a project.

Response 200

{
  "webhookUrl": "https://hooks.slack.com/services/...",
  "label": "#waitlist-alerts",
  "active": true,
  "connectedAt": "2026-04-10T12:00:00.000Z"
}

DELETE /slack/{projectId} Auth required

Remove the Slack integration. Notifications stop immediately.

Response 200

{ "success": true }

Error codes

All errors return a JSON body with an error string describing the problem. HTTP status codes follow standard conventions.

Status	Meaning	Common causes
400	Bad request	Missing or invalid request fields.
401	Unauthorized	Missing or expired `Authorization` token.
403	Forbidden	You do not own the requested project.
404	Not found	The project or resource does not exist.
429	Too many requests	Rate limit exceeded — retry after the window resets.
500	Internal server error	Something went wrong on our end. Try again shortly.

Error response shape

{ "error": "A valid email is required." }