# ALwrity Onboarding System - API Reference

## Overview

This document provides a comprehensive API reference for the ALwrity Onboarding System. All endpoints require authentication and return JSON responses.

## 🔐 Authentication

All endpoints require a valid Clerk JWT token in the Authorization header:

```
Authorization: Bearer <clerk_jwt_token>
```

## 📋 Core Endpoints

### Onboarding Status

#### GET `/api/onboarding/status`
Get the current onboarding status for the authenticated user.

**Response:**
```json
{
  "is_completed": false,
  "current_step": 2,
  "completion_percentage": 33.33,
  "next_step": 3,
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": null,
  "can_proceed_to_final": false
}
```

#### GET `/api/onboarding/progress`
Get the full onboarding progress data.

**Response:**
```json
{
  "steps": [
    {
      "step_number": 1,
      "title": "AI LLM Providers Setup",
      "description": "Configure your AI services",
      "status": "completed",
      "completed_at": "2024-01-15T10:35:00Z",
      "data": {...},
      "validation_errors": []
    }
  ],
  "current_step": 2,
  "started_at": "2024-01-15T10:30:00Z",
  "last_updated": "2024-01-15T10:35:00Z",
  "is_completed": false,
  "completed_at": null
}
```

### Step Management

#### GET `/api/onboarding/step/{step_number}`
Get data for a specific step.

**Parameters:**
- `step_number` (int): The step number (1-6)

**Response:**
```json
{
  "step_number": 1,
  "title": "AI LLM Providers Setup",
  "description": "Configure your AI services",
  "status": "in_progress",
  "completed_at": null,
  "data": {...},
  "validation_errors": []
}
```

#### POST `/api/onboarding/step/{step_number}/complete`
Mark a step as completed.

**Parameters:**
- `step_number` (int): The step number (1-6)

**Request Body:**
```json
{
  "data": {
    "api_keys": {
      "gemini": "your_gemini_key",
      "exa": "your_exa_key",
      "copilotkit": "your_copilotkit_key"
    }
  },
  "validation_errors": []
}
```

**Response:**
```json
{
  "message": "Step 1 completed successfully",
  "step_number": 1,
  "data": {...}
}
```

#### POST `/api/onboarding/step/{step_number}/skip`
Skip a step (for optional steps).

**Parameters:**
- `step_number` (int): The step number (1-6)

**Response:**
```json
{
  "message": "Step 2 skipped successfully",
  "step_number": 2
}
```

#### GET `/api/onboarding/step/{step_number}/validate`
Validate if user can access a specific step.

**Parameters:**
- `step_number` (int): The step number (1-6)

**Response:**
```json
{
  "can_proceed": true,
  "validation_errors": [],
  "step_status": "available"
}
```

### Onboarding Control

#### POST `/api/onboarding/start`
Start a new onboarding session.

**Response:**
```json
{
  "message": "Onboarding started successfully",
  "current_step": 1,
  "started_at": "2024-01-15T10:30:00Z"
}
```

#### POST `/api/onboarding/reset`
Reset the onboarding progress.

**Response:**
```json
{
  "message": "Onboarding progress reset successfully",
  "current_step": 1,
  "started_at": "2024-01-15T10:30:00Z"
}
```

#### GET `/api/onboarding/resume`
Get information for resuming onboarding.

**Response:**
```json
{
  "can_resume": true,
  "resume_step": 2,
  "current_step": 2,
  "completion_percentage": 33.33,
  "started_at": "2024-01-15T10:30:00Z",
  "last_updated": "2024-01-15T10:35:00Z"
}
```

#### POST `/api/onboarding/complete`
Complete the onboarding process.

**Response:**
```json
{
  "message": "Onboarding completed successfully",
  "completion_data": {...},
  "persona_generated": true,
  "environment_setup": true
}
```

## 🔑 API Key Management

### GET `/api/onboarding/api-keys`
Get all configured API keys (masked for security).

**Response:**
```json
{
  "api_keys": {
    "gemini": "********************abcd",
    "exa": "********************efgh",
    "copilotkit": "********************ijkl"
  },
  "total_providers": 3,
  "configured_providers": ["gemini", "exa", "copilotkit"]
}
```

### POST `/api/onboarding/api-keys`
Save an API key for a provider.

**Request Body:**
```json
{
  "provider": "gemini",
  "api_key": "your_api_key_here",
  "description": "Gemini API key for content generation"
}
```

**Response:**
```json
{
  "message": "API key for gemini saved successfully",
  "provider": "gemini",
  "status": "saved"
}
```

### GET `/api/onboarding/api-keys/validate`
Validate all configured API keys.

**Response:**
```json
{
  "validation_results": {
    "gemini": {
      "valid": true,
      "status": "active",
      "quota_remaining": 1000
    },
    "exa": {
      "valid": true,
      "status": "active",
      "quota_remaining": 500
    }
  },
  "all_valid": true,
  "total_providers": 2
}
```

## ⚙️ Configuration

### GET `/api/onboarding/config`
Get onboarding configuration and requirements.

**Response:**
```json
{
  "total_steps": 6,
  "required_steps": [1, 2, 3, 4, 6],
  "optional_steps": [5],
  "step_requirements": {
    "1": ["gemini", "exa", "copilotkit"],
    "2": ["website_url"],
    "3": ["research_preferences"],
    "4": ["personalization_settings"],
    "5": ["integrations"],
    "6": ["persona_generation"]
  }
}
```

### GET `/api/onboarding/providers`
Get setup information for all providers.

**Response:**
```json
{
  "providers": {
    "gemini": {
      "name": "Gemini AI",
      "description": "Advanced content generation",
      "setup_url": "https://ai.google.dev/",
      "required": true,
      "validation_endpoint": "https://generativelanguage.googleapis.com/v1beta/models"
    },
    "exa": {
      "name": "Exa AI",
      "description": "Intelligent web research",
      "setup_url": "https://exa.ai/",
      "required": true,
      "validation_endpoint": "https://api.exa.ai/v1/search"
    }
  }
}
```

### GET `/api/onboarding/providers/{provider}`
Get setup information for a specific provider.

**Parameters:**
- `provider` (string): Provider name (gemini, exa, copilotkit)

**Response:**
```json
{
  "name": "Gemini AI",
  "description": "Advanced content generation",
  "setup_url": "https://ai.google.dev/",
  "required": true,
  "validation_endpoint": "https://generativelanguage.googleapis.com/v1beta/models",
  "setup_instructions": [
    "Visit Google AI Studio",
    "Create a new API key",
    "Copy the API key",
    "Paste it in the form above"
  ]
}
```

### POST `/api/onboarding/providers/{provider}/validate`
Validate a specific provider's API key.

**Parameters:**
- `provider` (string): Provider name (gemini, exa, copilotkit)

**Request Body:**
```json
{
  "api_key": "your_api_key_here"
}
```

**Response:**
```json
{
  "valid": true,
  "status": "active",
  "quota_remaining": 1000,
  "provider": "gemini"
}
```

## 📊 Summary & Analytics

### GET `/api/onboarding/summary`
Get comprehensive onboarding summary for the final step.

**Response:**
```json
{
  "user_info": {
    "user_id": "user_123",
    "onboarding_started": "2024-01-15T10:30:00Z",
    "current_step": 6
  },
  "api_keys": {
    "gemini": "configured",
    "exa": "configured",
    "copilotkit": "configured"
  },
  "website_analysis": {
    "url": "https://example.com",
    "status": "completed",
    "style_analysis": "professional",
    "content_count": 25
  },
  "research_preferences": {
    "depth": "comprehensive",
    "auto_research": true,
    "fact_checking": true
  },
  "personalization": {
    "brand_voice": "professional",
    "target_audience": "B2B professionals",
    "content_types": ["blog_posts", "social_media"]
  }
}
```

### GET `/api/onboarding/website-analysis`
Get website analysis data.

**Response:**
```json
{
  "url": "https://example.com",
  "analysis_status": "completed",
  "content_analyzed": 25,
  "style_characteristics": {
    "tone": "professional",
    "voice": "authoritative",
    "complexity": "intermediate"
  },
  "target_audience": "B2B professionals",
  "content_themes": ["technology", "business", "innovation"]
}
```

### GET `/api/onboarding/research-preferences`
Get research preferences data.

**Response:**
```json
{
  "research_depth": "comprehensive",
  "auto_research_enabled": true,
  "fact_checking_enabled": true,
  "content_types": ["blog_posts", "articles", "social_media"],
  "research_sources": ["web", "academic", "news"]
}
```

## 👤 Business Information

### POST `/api/onboarding/business-info`
Save business information for users without websites.

**Request Body:**
```json
{
  "business_name": "Acme Corp",
  "industry": "Technology",
  "description": "AI-powered solutions",
  "target_audience": "B2B professionals",
  "brand_voice": "professional",
  "content_goals": ["lead_generation", "brand_awareness"]
}
```

**Response:**
```json
{
  "id": 1,
  "business_name": "Acme Corp",
  "industry": "Technology",
  "description": "AI-powered solutions",
  "target_audience": "B2B professionals",
  "brand_voice": "professional",
  "content_goals": ["lead_generation", "brand_awareness"],
  "created_at": "2024-01-15T10:30:00Z"
}
```

### GET `/api/onboarding/business-info/{id}`
Get business information by ID.

**Parameters:**
- `id` (int): Business information ID

**Response:**
```json
{
  "id": 1,
  "business_name": "Acme Corp",
  "industry": "Technology",
  "description": "AI-powered solutions",
  "target_audience": "B2B professionals",
  "brand_voice": "professional",
  "content_goals": ["lead_generation", "brand_awareness"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

### GET `/api/onboarding/business-info/user/{user_id}`
Get business information by user ID.

**Parameters:**
- `user_id` (int): User ID

**Response:**
```json
{
  "id": 1,
  "business_name": "Acme Corp",
  "industry": "Technology",
  "description": "AI-powered solutions",
  "target_audience": "B2B professionals",
  "brand_voice": "professional",
  "content_goals": ["lead_generation", "brand_awareness"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

### PUT `/api/onboarding/business-info/{id}`
Update business information.

**Parameters:**
- `id` (int): Business information ID

**Request Body:**
```json
{
  "business_name": "Acme Corp Updated",
  "industry": "Technology",
  "description": "Updated AI-powered solutions",
  "target_audience": "B2B professionals",
  "brand_voice": "professional",
  "content_goals": ["lead_generation", "brand_awareness", "thought_leadership"]
}
```

**Response:**
```json
{
  "id": 1,
  "business_name": "Acme Corp Updated",
  "industry": "Technology",
  "description": "Updated AI-powered solutions",
  "target_audience": "B2B professionals",
  "brand_voice": "professional",
  "content_goals": ["lead_generation", "brand_awareness", "thought_leadership"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}
```

## 🎭 Persona Management

### GET `/api/onboarding/persona/readiness/{user_id}`
Check if user has sufficient data for persona generation.

**Parameters:**
- `user_id` (int): User ID

**Response:**
```json
{
  "ready": true,
  "missing_data": [],
  "completion_percentage": 100,
  "recommendations": []
}
```

### GET `/api/onboarding/persona/preview/{user_id}`
Generate a preview of the writing persona without saving.

**Parameters:**
- `user_id` (int): User ID

**Response:**
```json
{
  "persona_preview": {
    "name": "Professional Content Creator",
    "voice": "authoritative",
    "tone": "professional",
    "style_characteristics": {
      "formality": "high",
      "complexity": "intermediate",
      "engagement": "informative"
    },
    "content_preferences": {
      "length": "medium",
      "format": "structured",
      "research_depth": "comprehensive"
    }
  },
  "generation_time": "2.5s",
  "confidence_score": 0.95
}
```

### POST `/api/onboarding/persona/generate/{user_id}`
Generate and save a writing persona from onboarding data.

**Parameters:**
- `user_id` (int): User ID

**Response:**
```json
{
  "persona_id": 1,
  "name": "Professional Content Creator",
  "voice": "authoritative",
  "tone": "professional",
  "style_characteristics": {...},
  "content_preferences": {...},
  "created_at": "2024-01-15T10:30:00Z",
  "status": "active"
}
```

### GET `/api/onboarding/persona/user/{user_id}`
Get all writing personas for the user.

**Parameters:**
- `user_id` (int): User ID

**Response:**
```json
{
  "personas": [
    {
      "id": 1,
      "name": "Professional Content Creator",
      "voice": "authoritative",
      "tone": "professional",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 1,
  "active_persona": 1
}
```

## 🚨 Error Responses

### 400 Bad Request
```json
{
  "detail": "Invalid request data",
  "error_code": "INVALID_REQUEST",
  "validation_errors": [
    "Field 'api_key' is required",
    "Field 'provider' must be one of: gemini, exa, copilotkit"
  ]
}
```

### 401 Unauthorized
```json
{
  "detail": "Authentication required",
  "error_code": "UNAUTHORIZED"
}
```

### 404 Not Found
```json
{
  "detail": "Step 7 not found",
  "error_code": "STEP_NOT_FOUND"
}
```

### 500 Internal Server Error
```json
{
  "detail": "Internal server error",
  "error_code": "INTERNAL_ERROR"
}
```

## 📝 Request/Response Models

### StepCompletionRequest
```json
{
  "data": {
    "api_keys": {
      "gemini": "string",
      "exa": "string",
      "copilotkit": "string"
    }
  },
  "validation_errors": ["string"]
}
```

### APIKeyRequest
```json
{
  "provider": "string",
  "api_key": "string",
  "description": "string"
}
```

### BusinessInfoRequest
```json
{
  "business_name": "string",
  "industry": "string",
  "description": "string",
  "target_audience": "string",
  "brand_voice": "string",
  "content_goals": ["string"]
}
```

## 🔄 Rate Limiting

- **Standard endpoints**: 100 requests per minute
- **API key validation**: 10 requests per minute
- **Persona generation**: 5 requests per minute

## 📊 Response Times

- **Status checks**: < 100ms
- **Step completion**: < 500ms
- **API key validation**: < 2s
- **Persona generation**: < 10s
- **Website analysis**: < 30s

---

*This API reference provides comprehensive documentation for all onboarding endpoints. For additional support, please refer to the main project documentation or contact the development team.*