API Reference

Example

curl "https://lighthouse.build/api/v1/waitlists/WAITLIST_ID/signups" \
  -H "Authorization: Bearer lh_your_api_key"

Response

{
  "waitlist_id": "abc-123",
  "name": "Beta Launch",
  "data": [
    { "email": "alice@example.com", "note": "Building a dev tool", "created_at": "2026-05-18T12:00:00Z" }
  ],
  "total": 87,
  "limit": 1000,
  "offset": 0,
  "has_more": false
}

Request body

{
  "email": "bob@example.com",
  "note": "Optional free-text (max 5000 chars)",
  "survey_answers": {
    "<question_id>": "answer",
    "<question_id>": ["multiple", "choices"]
  }
}

Answer value by question type

Example: simple signup

curl -X POST "https://lighthouse.build/api/v1/waitlists/WAITLIST_ID/signups" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "bob@example.com", "note": "Building a dev tool"}'

Example: signup with survey answers

curl -X POST "https://lighthouse.build/api/v1/waitlists/WAITLIST_ID/signups" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bob@example.com",
    "survey_answers": {
      "q_role": "Founder",
      "q_features": ["Analytics", "API"],
      "q_rating": "4"
    }
  }'

Response (201)

{
  "id": "f1e2d3c4-...",
  "email": "bob@example.com",
  "note": "Building a dev tool",
  "survey_answers": { "q_role": "Founder" },
  "created_at": "2026-05-28T12:00:00Z",
  "waitlist_id": "abc-123"
}

Example

curl "https://lighthouse.build/api/v1/newsletters/NEWSLETTER_ID/subscribers" \
  -H "Authorization: Bearer lh_your_api_key"

Response

{
  "newsletter_id": "def-456",
  "name": "Weekly Updates",
  "data": [
    { "email": "carol@example.com", "subscribed_at": "2026-05-18T12:00:00Z", "source": "manual" }
  ],
  "total": 53,
  "limit": 1000,
  "offset": 0,
  "has_more": false
}

Request body

{ "email": "dave@example.com" }

Example

curl -X POST "https://lighthouse.build/api/v1/newsletters/NEWSLETTER_ID/subscribers" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "dave@example.com"}'

Response (201)

{ "email": "dave@example.com", "newsletter_id": "def-456" }

Example

curl "https://lighthouse.build/api/v1/surveys/SURVEY_ID" \
  -H "Authorization: Bearer lh_your_api_key"

Response

{
  "survey_id": "abc-123",
  "name": "Onboarding",
  "collect_email": true,
  "questions": [
    {
      "id": "q1",
      "type": "text",
      "label": "What's your role?",
      "required": true
    },
    {
      "id": "q2",
      "type": "select",
      "label": "Company size?",
      "options": ["1-10", "11-50", "50+"],
      "required": true
    },
    {
      "id": "q3",
      "type": "multi_select",
      "label": "What are your goals?",
      "options": ["Growth", "Analytics", "Automation"],
      "required": false
    },
    {
      "id": "q4",
      "type": "rating",
      "label": "Experience level?",
      "required": true
    }
  ]
}

Question types

Request body

{
  "answers": {
    "<question_id>": "answer",  // text or single choice
    "<question_id>": ["multiple", "choices"],  // multiple choice
    "<question_id>": 4  // rating (1-5)
  },
  "email": "user@example.com"
}

Example: step-by-step onboarding

# Step 1: user signs up, you collect role
curl -X POST "https://lighthouse.build/api/v1/surveys/SURVEY_ID/responses" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "answers": {"q1": "Product Manager"}}'

# Step 2: next screen, collect company size
curl -X POST "https://lighthouse.build/api/v1/surveys/SURVEY_ID/responses" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "answers": {"q2": "11-50"}}'

# Step 3: collect goals
curl -X POST "https://lighthouse.build/api/v1/surveys/SURVEY_ID/responses" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "answers": {"q3": ["Growth", "Analytics"]}}'

All three calls merge into a single response. The final stored answers: {"q1": "Product Manager", "q2": "11-50", "q3": ["Growth", "Analytics"]}

Response (201 -- new response)

{
  "response_id": "resp-789",
  "survey_id": "abc-123"
}

Response (200 -- answers added to existing response)

{
  "response_id": "resp-789",
  "survey_id": "abc-123",
  "updated": true
}

Validation

• Required questions are only enforced when submitting all at once (not on partial updates)
• select values must match one of the defined options
• multi_select values must all be valid options
• rating must be a number between 1 and 5

Example

curl "https://lighthouse.build/api/v1/surveys/SURVEY_ID/responses?limit=100" \
  -H "Authorization: Bearer lh_your_api_key"

Response

{
  "survey_id": "abc-123",
  "name": "Onboarding",
  "data": [
    {
      "id": "resp-789",
      "answers": {
        "q1": "Product Manager",
        "q2": "11-50",
        "q3": ["Growth", "Analytics"],
        "q4": 4
      },
      "email": "user@example.com",
      "created_at": "2026-05-18T12:00:00Z"
    }
  ],
  "total": 42,
  "limit": 100,
  "offset": 0,
  "has_more": false
}

Example

curl "https://lighthouse.build/api/v1/feedback/COLLECTOR_ID" \
  -H "Authorization: Bearer lh_your_api_key"

Response

{
  "collector_id": "abc-123",
  "name": "App Feedback",
  "rating_mode": "stars",
  "categories": ["Bug", "Feature", "Praise", "Other"],
  "email_mode": "optional"
}

Rating modes

Categories

Categories are set per collector in the dashboard. When submitting feedback, the category value must match one of the collector's categories exactly. If the collector has no categories configured, omit the field.

Email modes

Request body (stars rating)

{
  "text": "The onboarding is confusing",
  "rating": 3,
  "category": "Feature",
  "email": "user@example.com",
  "context": { "page": "/settings", "device": "iOS" }
}

Request body (thumbs rating)

{
  "text": "Love the new dashboard!",
  "rating": 1,
  "category": "Praise",
  "email": "user@example.com"
}

Example

curl -X POST "https://lighthouse.build/api/v1/feedback/COLLECTOR_ID/submissions" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Love the new dashboard!", "rating": 5, "category": "Praise", "email": "user@example.com"}'

Response (201)

{ "id": "sub-789", "created_at": "2026-05-19T12:00:00Z" }

Query parameters

Example

curl "https://lighthouse.build/api/v1/feedback/COLLECTOR_ID/submissions?status=new&limit=50" \
  -H "Authorization: Bearer lh_your_api_key"

Response

{
  "data": [
    {
      "id": "sub-789",
      "text": "The onboarding is confusing",
      "rating": 3,
      "category": "Feature",
      "email": "user@example.com",
      "status": "new",
      "context": { "page": "/settings", "device": "iOS" },
      "created_at": "2026-05-19T12:00:00Z"
    }
  ],
  "total": 24,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

The id of each submission (e.g. sub-789) is the subId you pass to the status and reply endpoints below.

SUB_ID (the {subId} path segment) is a submission id from GET /feedback/{id}/submissions.

Request body

{
  "status": "shipped",
  "shipped_message": "We just redesigned the onboarding!"
}

Statuses

Example

curl -X PATCH "https://lighthouse.build/api/v1/feedback/COLLECTOR_ID/submissions/SUB_ID" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "shipped", "shipped_message": "Fixed in v2.1!"}'

Response

{ "id": "sub-789", "status": "shipped", "email_sent": true }

SUB_ID is a submission id from GET /feedback/{id}/submissions.

Request body

{ "body": "Thanks for the feedback! We're working on it." }

The submitter must have provided their email. Returns 400 if the submission has no email address.

Example

curl -X POST "https://lighthouse.build/api/v1/feedback/COLLECTOR_ID/submissions/SUB_ID/reply" \
  -H "Authorization: Bearer lh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "Thanks! This is on our roadmap for next week."}'

Response (201)

{ "reply_id": "rep-456", "sent_at": "2026-05-19T12:30:00Z" }

Query parameters

Example

curl "https://lighthouse.build/api/v1/projects/PROJECT_ID/emails?source=waitlist&limit=50" \
  -H "Authorization: Bearer lh_your_api_key"

Response

{
  "data": [
    {
      "email": "alice@example.com",
      "source": "waitlist",
      "source_name": "Beta Launch",
      "source_id": "abc-123",
      "created_at": "2026-05-18T12:00:00Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0,
  "has_more": true
}