Frontend Integration

​

Overview

​

Base Configuration

​

API Base URL

​

Authentication

const headers = {
  'Authorization': `Bearer ${supabaseToken}`,
  'Content-Type': 'application/json'
};

​

Auth + Subscription Flow

1. Checks session: On load, validates the Supabase session
2. Syncs profile: Calls POST /auth/sync to activate free plan or migrate pending subscriptions
3. Checks subscription: Calls GET /auth/me and reads subscription_status
4. Gates access: Renders the app if subscription_status === 'active', redirects to /subscribe otherwise

const response = await fetch(`${API_BASE_URL}/auth/me`, {
  headers: { 'Authorization': `Bearer ${token}` }
});
const profile = await response.json();

if (profile.subscription_status === 'active') {
  // Allow access
} else {
  // Redirect to /subscribe
}

​

Common Patterns

​

File Upload Flow

1. Initialize upload: POST /standards/{id}/uploads/init or POST /work-products/uploads/init
2. Upload file to the returned presigned URL
3. Complete upload: POST /standards/{id}/uploads/{upload_id}/complete

​

Analysis Tracking Flow

1. Start analysis: POST /analysis/gaps (returns immediately with job ID)
2. Poll analyses: GET /analysis/analyses?workspace_id=... to check status (pending → processing → completed)
3. Get results: GET /analysis/analyses/{id} for gaps and recommendations

​

Payment Flow

1. User selects a plan on the marketing site pricing section
2. Frontend calls POST /payments/create-checkout-session with the selected plan
3. User is redirected to Stripe Checkout
4. On success, Stripe redirects to STRIPE_SUCCESS_URL (the platform frontend /payment-success page)
5. The payment success page calls GET /payments/session-info/{session_id} and displays confirmation
6. On next login, POST /auth/sync migrates the pending subscription to the user profile

​

Error Handling

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {},
    "timestamp": "2026-01-15T10:30:00Z",
    "request_id": "req_123456789"
  }
}

​

Response Formats

​

Paginated Response

{
  "items": [],
  "total": 100,
  "page": 1,
  "limit": 20,
  "next_cursor": "cursor_string"
}

​

User Profile Response (GET /auth/me)

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "John Doe",
  "organization": "Acme Corp",
  "role": "engineer",
  "created_at": "2026-01-15T10:30:00Z",
  "last_login": "2026-03-03T14:00:00Z",
  "subscription_status": "active",
  "subscription_plan": "free"
}

​

Cross-Project URL References