API Reference

The Tap backend exposes a REST API running on Express (port 3001). Endpoints are organized into multiple groups: campaigns, conversations, mission wizard, analysis, metrics, integrations (Slack and Teams), plus supporting resources.

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.

Token validation includes anti-scanner logic -- email security tools that pre-fetch links won't accidentally start conversations. The GET /token/:token/validate endpoint checks token validity without side effects, and POST /token/:token/begin requires an explicit user action to create the conversation.

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
GET	/api/conversations/token/:token/validate	None	Validate a token without starting a conversation
POST	/api/conversations/token/:token/begin	None	Explicitly begin a conversation (prevents scanner ghost engagement)

Mission Wizard

AI-powered endpoints for crafting campaign questions. The unified endpoint handles the full wizard flow; the legacy endpoints are kept for backward compatibility.

Method	Endpoint	Auth	Description
POST	/api/mission/unified	Required	Full conversational wizard -- clarify, refine, and select in one flow
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

Metrics

Developer productivity metrics ingestion for correlation with feedback data.

Method	Endpoint	Auth	Description
POST	/api/v1/metrics/preview	Required	Preview a metrics file upload without writing data
POST	/api/v1/metrics/upload	Required	Process and import a metrics file
GET	/api/v1/metrics/runs	Required	List ingestion runs for the organization
GET	/api/v1/metrics/runs/:id	Required	Get details of a specific ingestion run

Rate limit: 10 uploads per hour per organization. Files must be under 50MB.

Integrations

Slack

Method	Endpoint	Auth	Description
GET	/api/slack/install	Required	Initiate Slack OAuth installation flow
GET	/api/slack/oauth/callback	None	Handle OAuth callback from Slack
POST	/api/slack/events	None	Receive Slack event webhooks (signature-verified)

Microsoft Teams

Method	Endpoint	Auth	Description
GET	/api/teams/install	Required	Initiate Teams OAuth installation flow
GET	/api/teams/oauth/callback	None	Handle OAuth callback from Teams
POST	/api/teams/webhook	None	Receive Teams webhook notifications

Supporting Resources

Method	Endpoint	Auth	Description
GET	/api/users/me	Required	Get current user profile
POST	/api/invites/accept	Required	Accept an organization invitation
POST	/api/feedback	Required	Submit product feedback

Route Files

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

Route File	Controller/Service	Handles
routes/campaigns.js	campaignController.js	Campaign CRUD, lifecycle, participants
routes/conversations.js	conversationController.js	Conversation management, messages, token validation
routes/mission.js	missionController.js	Mission wizard AI endpoints
routes/analysis.js	analysisController.js	Analysis generation and Q&A
routes/metrics.js	metricsController.js	Metrics upload, preview, ingestion runs
routes/slack.js	slackService.js	Slack OAuth, events, message delivery
routes/teams.js	teamsService.js	Teams OAuth, webhooks, message delivery
routes/users.js	--	User profile
routes/invites.js	--	Organization invitation acceptance
routes/feedback.js	--	Product feedback collection