kunthawat/ALwrity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d99c7c83a72211ddb7051614404e9cad69bc2bc7
ALwrity/backend/api/onboarding_utils/API_REFERENCE.md

14 KiB
Raw Blame History

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:

{
  "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:

{
  "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:

{
  "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:

{
  "data": {
    "api_keys": {
      "gemini": "your_gemini_key",
      "exa": "your_exa_key",
      "copilotkit": "your_copilotkit_key"
    }
  },
  "validation_errors": []
}

Response:

{
  "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:

{
  "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:

{
  "can_proceed": true,
  "validation_errors": [],
  "step_status": "available"
}

Onboarding Control

POST /api/onboarding/start

Start a new onboarding session.

Response:

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

POST /api/onboarding/reset

Reset the onboarding progress.

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "provider": "gemini",
  "api_key": "your_api_key_here",
  "description": "Gemini API key for content generation"
}

Response:

{
  "message": "API key for gemini saved successfully",
  "provider": "gemini",
  "status": "saved"
}

GET /api/onboarding/api-keys/validate

Validate all configured API keys.

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "api_key": "your_api_key_here"
}

Response:

{
  "valid": true,
  "status": "active",
  "quota_remaining": 1000,
  "provider": "gemini"
}

📊 Summary & Analytics

GET /api/onboarding/summary

Get comprehensive onboarding summary for the final step.

Response:

{
  "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:

{
  "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:

{
  "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:

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

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "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

{
  "detail": "Authentication required",
  "error_code": "UNAUTHORIZED"
}

404 Not Found

{
  "detail": "Step 7 not found",
  "error_code": "STEP_NOT_FOUND"
}

500 Internal Server Error

{
  "detail": "Internal server error",
  "error_code": "INTERNAL_ERROR"
}

📝 Request/Response Models

StepCompletionRequest

{
  "data": {
    "api_keys": {
      "gemini": "string",
      "exa": "string",
      "copilotkit": "string"
    }
  },
  "validation_errors": ["string"]
}

APIKeyRequest

{
  "provider": "string",
  "api_key": "string",
  "description": "string"
}

BusinessInfoRequest

{
  "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.

Reference in New Issue View Git Blame Copy Permalink