# DigiSim API Reference

> Backend API documentation for DigiSim using protobuf-based communication.

## Authentication
- **Email**: `/api/auth/email/signin` - EmailSignInRequest → AuthResponse
- **Google**: `/api/auth/google/signin` - OAuth token → AuthResponse  
- **Apple**: `/api/auth/apple/signin` - Apple identity token → AuthResponse
- **Refresh**: `/api/auth/refresh` - RefreshTokenRequest → New JWT

## Circuit Management
- **Save**: `/api/digisim/circuits/save` - SaveCircuitRequest with AI summary
- **List**: `/api/digisim/circuits/list` - GET with pagination
- **Delete**: `/api/digisim/circuits/delete` - DELETE with circuit ID
- **Load**: `/api/digisim/circuits/load/{id}` - GET circuit data

## Templates
- **List**: `/api/digisim/templates/list` - GET with category/difficulty filters
- **Featured**: `/api/digisim/templates/featured` - GET curated circuits
- **Admin CRUD**: Create/Update/Delete for admin users

## Subscription
- **Status**: `/api/subscription/status` - GET current plan details
- **Create**: `/api/subscription/create` - PayPal integration
- **Cancel**: `/api/subscription/cancel` - With reason and timing options
- **Update**: `/api/subscription/update-billing` - Billing cycle changes

## Data Models
- **AuthResponse**: JWT tokens + UserSubscriptionInfo + AvailableActionsInfo
- **UserSubscriptionInfo**: Plan type, features, quota, billing cycle
- **TemplateCircuit**: ID, name, category, difficulty, circuit data
- **CircuitFile**: Saved circuit with metadata and AI summary

## Security
- **JWT Authentication**: RS256 signed tokens
- **Rate Limiting**: Per-endpoint limits with headers
- **HTTPS Only**: All production endpoints secured