API Documentation

Introduction

The Prometheus NPS API allows you to collect and analyze Net Promoter Score (NPS) feedback from your users. This documentation covers all available endpoints and their usage.

Development Setup

To set up the project for development:

  1. Clone the repository and install dependencies:
    npm install
  2. Install Mailpit for local email testing:
    brew install axllent/apps/mailpit
  3. Create a .env file with the following variables: 
    SUPABASE_URL=your-supabase-url
SUPABASE_ANON_KEY=your-supabase-anon-key
OPENAI_API_KEY=your-openai-api-key
RESEND_API_KEY=your-resend-api-key
JWT_SECRET=your-jwt-secret
ADMIN_API_KEY=your-admin-api-key
  4. Start Mailpit in a separate terminal:
    mailpit
  5. Start the development server:
    npm run dev

The server will run at http://localhost:3002, and you can view development emails at http://localhost:8025.

Authentication

Admin endpoints require an API key to be included in the request headers:

X-API-Key: your-api-key

Endpoints

Generate Form Link

Generate a pre-populated feedback form link for a specific user.

POST /api/generate-form-link

Requires API Key

Request Body

{
  "name": "John Doe",
  "email": "john@example.com"
}

Response

{
  "message": "Form link generated and sent to email",
  "url": "https://your-domain.com/?token=..."
}

Submit Feedback

Submit NPS feedback for a user.

POST /api/feedback

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "npsScore": 9,
  "feedback": "Great service! Would definitely recommend."
}

Response

{
  "message": "Feedback submitted successfully."
}

Get Feedback Summary

Get an AI-generated summary of all feedback.

GET /api/summary

Requires API Key

Response

{
  "summary": "Overall positive feedback with an average NPS score of 8.5..."
}

Email Testing

The application uses different email providers based on the environment:

  • Development: Uses Mailpit (http://localhost:8025) for local email testing
  • Production: Uses Resend for reliable email delivery

All emails in development mode can be viewed in the Mailpit web interface at http://localhost:8025.

Security & Rate Limits

Rate Limiting

  • General endpoints: 100 requests per 15 minutes per IP
  • Form generation: 5 requests per 15 minutes per IP

Security Features

  • Helmet.js for secure HTTP headers
  • JWT-based form pre-population
  • API key authentication for admin endpoints
  • Input validation and sanitization
  • XSS protection
  • CSRF protection

Features

  • Modern UI with Tailwind CSS and Alpine.js
  • Vector embeddings for feedback analysis
  • AI-powered feedback summarization
  • Secure form pre-population
  • Development email testing with Mailpit
  • Production email delivery with Resend
  • Rate limiting and security features
  • Comprehensive input validation
  • API documentation