Support & Feedback API¶
Status: Implemented
Last Updated: January 10, 2026
Location: app/api/support_routes.py
Overview¶
The Support & Feedback API provides endpoints for users to submit bug reports, provide feedback, and create general support tickets. This supports user stories US-11.4 (Report a Problem) and US-11.5 (Submit Feedback).
Endpoints¶
Report a Bug¶
Submit a bug report with optional reproduction steps and device info.
Request Body:
{
"description": "The calendar integration shows wrong dates",
"steps_to_reproduce": "1. Open calendar\n2. Check tomorrow's events\n3. Dates are off by one day",
"expected_behavior": "Dates should match my Google Calendar",
"actual_behavior": "All dates are shifted by one day",
"device_info": "iPhone 15 Pro, iOS 18.1",
"app_version": "1.0.0",
"screenshot_urls": ["https://..."]
}
Response (200 OK):
{
"ticket_id": "uuid",
"status": "open",
"message": "Thank you for reporting this bug. We'll investigate and get back to you.",
"created_at": "2026-01-10T12:00:00Z"
}
Rate Limit: 5 reports per hour per user
Submit Feedback¶
Submit product feedback including feature requests, improvements, or complaints.
Request Body:
{
"category": "feature_request",
"description": "It would be great if Sage could track my fitness goals",
"rating": 4,
"feature_name": "fitness_tracking",
"would_recommend": true
}
Category Options:
- feature_request - Request for new functionality
- improvement - Enhancement to existing feature
- complaint - Issue or dissatisfaction
- praise - Positive feedback
- other - General feedback
Response (200 OK):
{
"feedback_id": "uuid",
"message": "Thanks for the feature request! We review all suggestions for our roadmap.",
"created_at": "2026-01-10T12:00:00Z"
}
Rate Limit: 10 submissions per hour per user
Create Support Ticket¶
Create a general support ticket for billing, technical, or account issues.
Request Body:
{
"ticket_type": "billing",
"subject": "Charged twice for subscription",
"description": "I was charged $15 twice on January 5th. Please refund the duplicate charge.",
"priority": "high"
}
Ticket Types:
- bug - Bug report (prefer /report-bug for more details)
- technical - Technical issues
- billing - Payment/subscription issues
- account - Account access issues
- other - General inquiries
Priority Levels:
- low - Non-urgent, can wait
- medium - Standard priority (default)
- high - Needs attention soon
- urgent - Critical issue
Response (200 OK):
{
"ticket_id": "uuid",
"ticket_type": "billing",
"status": "open",
"priority": "high",
"message": "Your support ticket has been created. We typically respond within 24 hours.",
"created_at": "2026-01-10T12:00:00Z"
}
Rate Limit: 5 tickets per hour per user
List My Tickets¶
Get a list of the user's support tickets.
Query Parameters:
- status (optional): Filter by status (open, in_progress, resolved, closed)
- limit (optional): Max tickets to return (default: 20)
- offset (optional): Pagination offset (default: 0)
Response (200 OK):
{
"tickets": [
{
"ticket_id": "uuid",
"ticket_type": "billing",
"subject": "Charged twice for subscription",
"status": "in_progress",
"priority": "high",
"created_at": "2026-01-10T12:00:00Z",
"updated_at": "2026-01-10T14:00:00Z"
}
],
"total": 1
}
Get Ticket Detail¶
Get detailed view of a specific ticket, including any resolution.
Response (200 OK):
{
"ticket_id": "uuid",
"ticket_type": "billing",
"subject": "Charged twice for subscription",
"description": "I was charged $15 twice on January 5th...",
"status": "resolved",
"priority": "high",
"admin_notes": null,
"resolution": "Refund of $15 processed. Should appear in 3-5 business days.",
"created_at": "2026-01-10T12:00:00Z",
"updated_at": "2026-01-10T16:00:00Z",
"resolved_at": "2026-01-10T16:00:00Z"
}
Error Responses:
- 404 - Ticket not found or belongs to another user
Database Schema¶
support_tickets¶
CREATE TABLE support_tickets (
id UUID PRIMARY KEY,
user_id UUID NOT NULL REFERENCES users(id),
ticket_type VARCHAR(50) NOT NULL,
subject VARCHAR(255) NOT NULL,
description TEXT NOT NULL,
status VARCHAR(50) DEFAULT 'open',
priority VARCHAR(20) DEFAULT 'medium',
admin_notes TEXT,
resolution TEXT,
assigned_to VARCHAR(100),
meta_data JSONB DEFAULT '{}',
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
resolved_at TIMESTAMPTZ
);
user_feedback¶
CREATE TABLE user_feedback (
id UUID PRIMARY KEY,
user_id UUID NOT NULL REFERENCES users(id),
category VARCHAR(50) NOT NULL,
description TEXT NOT NULL,
rating INTEGER CHECK (rating >= 1 AND rating <= 5),
feature_name VARCHAR(100),
would_recommend BOOLEAN,
status VARCHAR(50) DEFAULT 'received',
admin_response TEXT,
meta_data JSONB DEFAULT '{}',
created_at TIMESTAMPTZ DEFAULT NOW(),
reviewed_at TIMESTAMPTZ
);
Companion Integration¶
The support system can be triggered from companion chat:
User via iMessage: - "report bug" → Creates bug ticket - "I have feedback" → Creates feedback entry - "feature request" → Creates feature_request feedback
Helper Function:
from app.api.support_routes import create_ticket_from_companion
ticket_id = await create_ticket_from_companion(
user_id="user-uuid",
ticket_type="bug", # or "feedback"
description="What the user said",
db=db_session
)
Related User Stories¶
- US-11.4: Report a Problem - Bug reports via web/iMessage
- US-11.5: Submit Feedback - Feature requests and feedback
Security Considerations¶
- Authentication Required - All endpoints require valid JWT
- Rate Limiting - Prevents spam (5 bugs/hour, 10 feedback/hour)
- User Isolation - Users can only view their own tickets (RLS enabled)
- Input Validation - Description length limits, enum validation
- No PII in Logs - Ticket content not logged
Future Enhancements¶
- Email notifications when ticket status changes
- Admin dashboard for ticket management
- Attachment/screenshot upload to Supabase Storage
- Ticket threading for back-and-forth with support
- Auto-categorization using LLM