Skip to content

API Reference

Complete API endpoint documentation.

Auto-Generated Documentation

FastAPI provides interactive API docs:

  • Swagger UI: http://localhost:8020/docs
  • ReDoc: http://localhost:8020/redoc

API Endpoints

Authentication (/api/auth)

All Tiers:

  • POST /api/auth/login - Email/password login
  • POST /api/auth/signup - Create account
  • GET /api/auth/logout - Logout
  • GET /api/auth/current - Get current user
  • GET /api/auth/google/authorize - Start Google OAuth
  • GET /api/auth/google_callback - Google OAuth callback
  • POST /api/auth/forgot-password - Request password reset
  • POST /api/auth/reset-password - Reset password with token
  • PUT /api/auth/profile - Update user profile

Articles (/api/articles)

All Tiers:

  • GET /api/articles - List articles
  • POST /api/articles - Create article
  • GET /api/articles/{id} - Get article
  • PUT /api/articles/{id} - Update article
  • DELETE /api/articles/{id} - Delete article

Payments (/api/payments) - Top G+

  • GET /api/payments/products - List Stripe products
  • POST /api/payments/checkout/create - Create checkout session
  • POST /api/payments/portal/create - Create customer portal session
  • POST /api/payments/webhook - Stripe webhook handler
  • POST /api/payments/cancel-subscription - Cancel subscription

Analytics (/api/analytics) - Top G+

  • GET /api/analytics/basic - Basic analytics (Starter+)
  • GET /api/analytics/advanced - Advanced analytics (Pro+)
  • GET /api/analytics/reporting - Premium reporting (Premium+)
  • GET /api/analytics/team - Team analytics (Enterprise)

Integrations (/api/integrations) - Top G+

  • GET /api/integrations - List available integrations
  • GET /api/integrations/status - Integration status
  • GET /api/integrations/{id} - Integration details
  • POST /api/integrations/{id}/setup - Setup integration

Plans (/api/plans) - Top G+

  • GET /api/plans/me - Current user's plan info
  • POST /api/plans/check-feature - Check feature access
  • GET /api/plans/upgrades - Available upgrades
  • GET /api/plans/features - All features
  • GET /api/plans/comparison - Plan comparison

Upgrades (/api/upgrades) - Top G+

  • GET /api/upgrades/options - Upgrade options
  • POST /api/upgrades/checkout - Create upgrade checkout
  • POST /api/upgrades/proration-preview - Preview proration

Authentication

JWT Token Authentication

Login to get token: ```bash curl -X POST http://localhost:8020/api/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]","password":"password123"}'

Text Only
1
2
3
4
5
Response:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs..."
}

Use token in requests:

Bash
1
2
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8020/api/articles

Or use cookie (automatic in browser).

TypeScript API Client

Auto-generated TypeScript client in frontend/src/client/.

Generate Client

```bash

ALWAYS run after backend API changes

task frontend:generate-client

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
### Use in Frontend

```typescript
import { ArticlesService } from '@/client';

// Direct service call
const articles = await ArticlesService.listArticles();

// Or use React Query hook (recommended)
import { useArticles } from '@/hooks/api/useArticles';
const { data: articles } = useArticles();

Request/Response Examples

Create Article

Request:

Bash
1
2
3
4
5
6
7
8
9
POST /api/articles
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "title": "My Article",
  "content": "Article content here",
  "is_published": true
}

Response:

JSON
1
2
3
4
5
6
7
8
9
{
  "id": 1,
  "title": "My Article",
  "content": "Article content here",
  "author": "[email protected]",
  "is_published": true,
  "published_at": "2024-01-01T12:00:00",
  "user_id": "uuid-here"
}

Create Checkout Session (Top G+)

Request:

Bash
1
2
3
4
5
6
7
8
POST /api/payments/checkout/create
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "payment_type": "subscription",
  "tier": "premium"
}

Response:

JSON
1
2
3
4
5
{
  "session_id": "cs_test_...",
  "url": "https://checkout.stripe.com/...",
  "customer_id": "cus_..."
}

Error Responses

Standard Error Format

JSON
1
2
3
4
5
{
  "detail": "Error message",
  "type": "error_type",
  "error_code": "SPECIFIC_CODE"
}

Common Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad request
  • 401 - Unauthorized (login required)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not found
  • 422 - Validation error
  • 500 - Server error

API Base URL

  • Local: http://localhost:8020
  • Production: https://yourdomain.com

Rate Limiting

Currently no rate limiting implemented.
Add if needed for production.

CORS Configuration

Configured in main.py:

Python
1
2
3
4
allow_origins=[
    "http://localhost:5173",  # Vite dev
    "https://yourdomain.com",  # Production
]

Update for your production domain.

Learning Resources

Learn FastAPI: Free interactive tutorials for mastering FastAPI.