API Reference

The Tap backend exposes a REST API running on Express (port 3001). Endpoints are organized into four groups: campaigns, conversations, mission wizard, and analysis.

Authentication: Endpoints marked "Required" expect a Supabase JWT in the Authorization: Bearer <token> header. Token-based endpoints use a unique participant token instead.

Campaign Management

Method	Endpoint	Auth	Description
GET	/api/campaigns	Required	List all campaigns for the authenticated user
GET	/api/campaigns?archived=true	Required	List archived campaigns
GET	/api/campaigns/:id	Required	Get a single campaign by ID
POST	/api/campaigns	Required	Create a new campaign
PUT	/api/campaigns/:id	Required	Update campaign details
DELETE	/api/campaigns/:id	Required	Delete a campaign
POST	/api/campaigns/:id/launch	Required	Launch campaign (sends invitations)
PATCH	/api/campaigns/:id/status	Required	Change campaign status
POST	/api/campaigns/:id/clone	Required	Clone a campaign's settings
POST	/api/campaigns/:id/pause	Required	Pause an active campaign
POST	/api/campaigns/:id/resume	Required	Resume a paused campaign
POST	/api/campaigns/:id/archive	Required	Archive a completed campaign
POST	/api/campaigns/:id/unarchive	Required	Unarchive a campaign

Participants

Method	Endpoint	Auth	Description
POST	/api/campaigns/:id/participants	Required	Upload participants via CSV file
GET	/api/campaigns/:id/participants	Required	List all participants for a campaign
POST	/api/campaigns/:id/send-invitations	Required	Send invitation emails to all participants

Conversations (Authenticated)

For campaign creators viewing conversation data.

Method	Endpoint	Auth	Description
GET	/api/conversations/campaign/:campaignId	Required	List all conversations for a campaign
GET	/api/conversations/:id	Required	Get a single conversation with messages
POST	/api/conversations/start	Required	Start a new conversation

Conversations (Public / Token-Based)

For participants responding to campaigns. No login required.

Method	Endpoint	Auth	Description
GET	/api/conversations/token/:token	None	Get conversation by participant token
POST	/api/conversations/:id/messages	None	Add a message to a conversation
POST	/api/conversations/:id/respond	None	Submit a final response

Mission Wizard

AI-powered endpoints for crafting campaign questions. These are used during campaign creation.

Method	Endpoint	Auth	Description
POST	/api/mission/clarify	None	Analyze initial input, extract topic/audience/criteria
POST	/api/mission/refine	None	Generate unbiased question options
POST	/api/mission/generate-summary	None	Generate engaging email summary for invitations

Analysis

Method	Endpoint	Auth	Description
GET	/api/campaigns/:id/analysis	Required	Get full AI analysis (sentiment, themes, summary, groups)
POST	/api/campaigns/:id/query	Required	Ask a natural language question about campaign responses

Health Check

Method	Endpoint	Auth	Description
GET	/health	None	Returns backend status

Route Files

The API is organized into four route files, each with a corresponding controller:

Route File	Controller	Handles
routes/campaigns.js	campaignController.js	Campaign CRUD, lifecycle, participants
routes/conversations.js	conversationController.js	Conversation management, messages
routes/mission.js	missionController.js	Mission wizard AI endpoints
routes/analysis.js	analysisController.js	Analysis generation and Q&A