API Documentation

This page renders the consolidated API specification from docs/API-DOCUMENTATION.md so developers can quickly inspect integrated endpoints without leaving the app.

Last updated on 6/21/2026, 6:50:26 AM

Rachana Finance & Technology - API Documentation

📋 Table of Contents

  1. API Overview
  2. Authentication
  3. Authentication Endpoints
  4. AI & Analysis Endpoints
  5. Utility Endpoints
  6. Error Handling
  7. Rate Limiting
  8. Request/Response Examples

🔧 API Overview

The Rachana Finance API is built using Next.js API Routes and provides RESTful endpoints for:

  • User authentication and profile management
  • AI-powered financial analysis
  • Video and document processing
  • Real-time chat functionality
  • Content analysis and insights

Base URL: https://yourdomain.com/api

Content Type: application/json

Authentication: Cookie-based JWT tokens

🔐 Authentication

All protected endpoints require authentication via secure httpOnly cookies containing JWT tokens.

Authentication Flow

  1. User logs in via /api/auth/signin
  2. Server sets secure cookies with access tokens
  3. Subsequent requests include cookies automatically
  4. Server validates tokens on each protected request

Cookie Names

  • supabase-auth-token - Main authentication token
  • Session management handled by Supabase

🔑 Authentication Endpoints

POST /api/auth/signin

User login endpoint.

Request Body:

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response (Success - 200):

{
  "message": "Login successful",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "user_metadata": {}
  }
}

Response (Error - 400/401):

{
  "error": "Invalid credentials"
}

POST /api/auth/signup

User registration endpoint.

Request Body:

{
  "email": "newuser@example.com",
  "password": "securepassword",
  "confirmPassword": "securepassword"
}

Response (Success - 201):

{
  "message": "User created successfully",
  "user": {
    "id": "uuid",
    "email": "newuser@example.com"
  }
}

POST /api/auth/signout

User logout endpoint.

Headers Required:

Cookie: supabase-auth-token=...

Response (Success - 200):

{
  "message": "Logged out successfully"
}

GET /api/auth/profile

Get current user profile.

Headers Required:

Cookie: supabase-auth-token=...

Response (Success - 200):

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "user_metadata": {
      "full_name": "John Doe",
      "avatar_url": "https://..."
    },
    "created_at": "2024-01-01T00:00:00Z"
  }
}

POST /api/auth/profile

Update user profile.

Headers Required:

Cookie: supabase-auth-token=...

Request Body:

{
  "full_name": "John Doe Updated",
  "avatar_url": "https://newavatar.com/image.jpg"
}

Response (Success - 200):

{
  "message": "Profile updated successfully",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "user_metadata": {
      "full_name": "John Doe Updated",
      "avatar_url": "https://newavatar.com/image.jpg"
    }
  }
}

🤖 AI & Analysis Endpoints

POST /api/chat

OpenAI-powered financial chat assistant.

Headers Required:

Cookie: supabase-auth-token=...
Content-Type: application/json

Request Body:

{
  "message": "What are the best investment strategies for 2024?",
  "conversation_id": "optional-uuid"
}

Response (Success - 200):

{
  "response": "Based on current market trends, here are some investment strategies...",
  "conversation_id": "uuid",
  "token_usage": {
    "prompt_tokens": 150,
    "completion_tokens": 300,
    "total_tokens": 450
  }
}

POST /api/gemini-chat

Google Gemini AI chat interface.

Headers Required:

Cookie: supabase-auth-token=...
Content-Type: application/json

Request Body:

{
  "message": "Analyze this financial document",
  "image": "base64-encoded-image-data", // optional
  "conversation_history": [
    {
      "role": "user",
      "content": "Previous message"
    }
  ]
}

Response (Success - 200):

{
  "response": "Analysis of the financial document shows...",
  "token_usage": {
    "prompt_token_count": 200,
    "candidates_token_count": 400,
    "total_token_count": 600
  }
}

GET /api/gemini-chat

Get chat history.

Headers Required:

Cookie: supabase-auth-token=...

Query Parameters:

  • conversation_id (optional): Specific conversation ID
  • limit (optional): Number of messages to return (default: 50)

Response (Success - 200):

{
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "content": "User message",
      "timestamp": "2024-01-01T00:00:00Z"
    },
    {
      "id": "uuid",
      "role": "model",
      "content": "AI response",
      "timestamp": "2024-01-01T00:00:01Z"
    }
  ],
  "total_count": 10
}

PUT /api/gemini-chat

Clear chat history.

Headers Required:

Cookie: supabase-auth-token=...

Response (Success - 200):

{
  "message": "Chat history cleared successfully"
}

POST /api/video-analysis

Analyze video content using AI.

Headers Required:

Cookie: supabase-auth-token=...
Content-Type: multipart/form-data

Request Body (Form Data):

video: File // Video file (MP4, WebM, MOV)
OR
youtube_url: string // YouTube video URL

Response (Success - 200):

{
  "analysis": {
    "summary": "This video discusses quarterly earnings...",
    "insights": [
      "Revenue increased by 15% year-over-year",
      "New product launches expected in Q3",
      "Market expansion into Asia mentioned"
    ],
    "stock_tickers": ["AAPL", "MSFT", "GOOGL"],
    "captions": [
      {
        "timestamp": 10.5,
        "text": "Welcome to our quarterly earnings call",
        "confidence": 0.95
      }
    ],
    "analysisData": {
      "duration": 1800,
      "frameCount": 54000,
      "audioAnalysis": "Clear speech detected throughout",
      "visualAnalysis": "Professional presentation format"
    }
  },
  "processing_time": 45.2
}

POST /api/video-chat

Chat about analyzed video content.

Headers Required:

Cookie: supabase-auth-token=...
Content-Type: application/json

Request Body:

{
  "message": "What were the key financial metrics mentioned?",
  "video_analysis_id": "uuid",
  "context": {
    "video_summary": "Previous analysis summary...",
    "key_points": ["Point 1", "Point 2"]
  }
}

Response (Success - 200):

{
  "response": "The key financial metrics mentioned include...",
  "relevant_timestamps": [120.5, 245.8, 890.2],
  "confidence": 0.89
}

POST /api/url-analysis

Analyze web page content.

Headers Required:

Cookie: supabase-auth-token=...
Content-Type: application/json

Request Body:

{
  "url": "https://example.com/financial-article",
  "analysis_type": "financial" // or "general"
}

Response (Success - 200):

{
  "analysis": {
    "title": "Article Title",
    "summary": "Article summary...",
    "key_points": [
      "Point 1",
      "Point 2"
    ],
    "financial_metrics": {
      "mentioned_stocks": ["AAPL", "TSLA"],
      "price_targets": [
        {
          "stock": "AAPL",
          "target": 180,
          "analyst": "Goldman Sachs"
        }
      ]
    },
    "sentiment": "positive",
    "confidence": 0.92
  },
  "content": {
    "raw_text": "Full article text...",
    "word_count": 1250,
    "read_time": "5 minutes"
  }
}

GET /api/url-analysis

Get URL analysis history.

Headers Required:

Cookie: supabase-auth-token=...

Query Parameters:

  • limit (optional): Number of results (default: 20)
  • offset (optional): Pagination offset (default: 0)

Response (Success - 200):

{
  "analyses": [
    {
      "id": "uuid",
      "url": "https://example.com/article",
      "title": "Article Title",
      "summary": "Brief summary...",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total_count": 45,
  "has_more": true
}

🔧 Utility Endpoints

GET /api/list-models

Get available AI models.

Response (Success - 200):

{
  "models": [
    {
      "id": "gemini-pro",
      "name": "Gemini Pro",
      "type": "text",
      "capabilities": ["text-generation", "analysis"]
    },
    {
      "id": "gemini-pro-vision",
      "name": "Gemini Pro Vision",
      "type": "multimodal",
      "capabilities": ["text-generation", "image-analysis", "video-analysis"]
    }
  ]
}

POST /api/files/avatar

Upload user avatar.

Headers Required:

Cookie: supabase-auth-token=...
Content-Type: multipart/form-data

Request Body (Form Data):

avatar: File // Image file (JPG, PNG, WebP)

Response (Success - 200):

{
  "message": "Avatar uploaded successfully",
  "avatar_url": "https://storage.supabase.co/avatar-url",
  "file_size": 245760
}

POST /api/forms

Submit contact/inquiry forms.

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "subject": "Investment Inquiry",
  "message": "I'm interested in your services...",
  "type": "contact" // or "inquiry", "support"
}

Response (Success - 200):

{
  "message": "Form submitted successfully",
  "reference_id": "uuid",
  "estimated_response_time": "24 hours"
}

GET /api/forms

Get form submissions (admin only).

Headers Required:

Cookie: supabase-auth-token=...
Authorization: Admin

Query Parameters:

  • type (optional): Form type filter
  • status (optional): Submission status
  • limit (optional): Number of results

Response (Success - 200):

{
  "submissions": [
    {
      "id": "uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "subject": "Investment Inquiry",
      "type": "contact",
      "status": "pending",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total_count": 25
}

GET /api/test-env

Environment and health check.

Response (Success - 200):

{
  "status": "healthy",
  "environment": "production",
  "version": "1.0.0",
  "services": {
    "database": "connected",
    "ai_services": "available",
    "storage": "accessible"
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

GET /api/hello

Basic API health check.

Response (Success - 200):

{
  "message": "Hello from Rachana Finance API",
  "status": "operational",
  "timestamp": "2024-01-01T00:00:00Z"
}

POST /api/hello

Echo test endpoint.

Request Body:

{
  "message": "Test message"
}

Response (Success - 200):

{
  "echo": "Test message",
  "received_at": "2024-01-01T00:00:00Z"
}

📝 Form Submission Endpoints

Note: All form submissions are stored in a separate PostgreSQL database (configured via POSTGRES_* env vars), independent of the Supabase Auth database.

POST /api/forms/consultation

Submit a consultation scheduling request.

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+91-9876543210",
  "company": "Example Corp",
  "service_type": "Wealth Management",
  "preferred_date": "2024-12-15",
  "preferred_time": "10:00 AM - 12:00 PM",
  "message": "Looking for wealth management consultation"
}

Response (Success - 201):

{
  "message": "Thank you! Your consultation request has been submitted successfully.",
  "consultation_id": "uuid"
}

GET /api/forms/consultation

Get all consultation requests (authenticated).

Headers Required:

Cookie: supabase-auth-token=...

Response (Success - 200):

{
  "consultations": [
    {
      "id": "uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+91-9876543210",
      "company": "Example Corp",
      "service_type": "Wealth Management",
      "preferred_date": "2024-12-15",
      "preferred_time": "10:00 AM - 12:00 PM",
      "message": "Looking for wealth management consultation",
      "status": "pending",
      "submitted_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /api/forms/careers

Submit a job application.

Request Body:

{
  "full_name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+91-9876543211",
  "position": "Software Engineer",
  "location": "Bangalore",
  "experience_years": 5,
  "linkedin_url": "https://linkedin.com/in/janesmith",
  "cover_letter": "I am excited to apply for the Software Engineer position...",
  "resume_url": "https://example.com/resume.pdf"
}

Response (Success - 201):

{
  "message": "Thank you for applying! We have received your application and will review it shortly.",
  "application_id": "uuid"
}

GET /api/forms/careers

Get all career applications.

Response (Success - 200):

{
  "applications": [
    {
      "id": "uuid",
      "full_name": "Jane Smith",
      "email": "jane@example.com",
      "position": "Software Engineer",
      "location": "Bangalore",
      "experience_years": 5,
      "status": "pending",
      "submitted_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /api/forms/contact

Submit a contact form inquiry.

Request Body:

{
  "name": "Alice Brown",
  "email": "alice@example.com",
  "phone": "+91-9876543212",
  "company": "Tech Solutions Ltd",
  "message": "I would like to know more about your services",
  "subject": "General Inquiry"
}

Response (Success - 201):

{
  "message": "Thank you! Your message has been received. We will get back to you soon.",
  "submission_id": "uuid"
}

GET /api/forms/contact

Get all contact submissions (authenticated).

Headers Required:

Cookie: supabase-auth-token=...

Response (Success - 200):

{
  "submissions": [
    {
      "id": "uuid",
      "name": "Alice Brown",
      "email": "alice@example.com",
      "subject": "General Inquiry",
      "submitted_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /api/forms/investor-inquiry

Submit an investor inquiry.

Request Body:

{
  "full_name": "Robert Investor",
  "email": "robert@vc.com",
  "phone": "+91-9876543213",
  "company": "VC Capital",
  "investment_interest": "Series A",
  "fund_size": "50Cr+",
  "focus_areas": ["Fintech", "AI"],
  "message": "We are interested in discussing investment opportunities"
}

Response (Success - 201):

{
  "message": "Thank you for your interest! Our investor relations team will contact you soon.",
  "inquiry_id": "uuid"
}

GET /api/forms/investor-inquiry

Get all investor inquiries.

Response (Success - 200):

{
  "inquiries": [
    {
      "id": "uuid",
      "full_name": "Robert Investor",
      "email": "robert@vc.com",
      "company": "VC Capital",
      "investment_interest": "Series A",
      "status": "new",
      "submitted_at": "2024-01-01T00:00:00Z"
    }
  ]
}

🗑️ Account Management

GET /api/auth/delete-profile

Get information about account deletion process (public endpoint for Google Play compliance).

Response (Success - 200):

{
  "title": "Account Deletion Information",
  "description": "Information about how to request account deletion",
  "process": [
    "Log in to your account",
    "Navigate to Settings",
    "Scroll to the Danger Zone section",
    "Click 'Delete Account'",
    "Confirm deletion by typing DELETE",
    "Your account will be permanently deleted"
  ],
  "data_retention": {
    "user_data": "Deleted immediately",
    "transaction_history": "Retained for 7 years per financial regulations",
    "anonymized_analytics": "Retained indefinitely"
  },
  "contact": {
    "email": "support@rachana.finance",
    "support_url": "https://rachana.finance/contact"
  }
}

POST /api/auth/delete-profile

Delete user account and all associated data (authenticated users only).

Headers Required:

Cookie: supabase-auth-token=...
Content-Type: application/json

Request Body:

{
  "confirmation": "DELETE"
}

Response (Success - 200):

{
  "message": "Account deleted successfully",
  "deleted_at": "2024-01-01T00:00:00Z"
}

Response (Error - 400):

{
  "error": "Invalid confirmation. Type DELETE to confirm."
}

⚠️ Error Handling

Common Error Responses

400 Bad Request

{
  "error": "Invalid request format",
  "details": "Missing required field: email",
  "code": "VALIDATION_ERROR"
}

401 Unauthorized

{
  "error": "Authentication required",
  "code": "UNAUTHORIZED"
}

403 Forbidden

{
  "error": "Insufficient permissions",
  "code": "FORBIDDEN"
}

404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retry_after": 60,
  "code": "RATE_LIMIT_EXCEEDED"
}

500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "reference_id": "uuid"
}

503 Service Unavailable

{
  "error": "AI service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE",
  "retry_after": 300
}

🚦 Rate Limiting

Rate Limits by Endpoint

Endpoint Category Limit Window
Authentication 5 requests 1 minute
AI Chat 20 requests 1 minute
Video Analysis 3 requests 5 minutes
URL Analysis 10 requests 1 minute
File Upload 5 requests 1 minute
General API 100 requests 1 minute

Rate Limit Headers

All responses include rate limiting headers:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1704067200

📝 Request/Response Examples

Complete Chat Session Example

1. User Login

curl -X POST https://api.rachana.com/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "investor@example.com",
    "password": "securepass123"
  }'

2. Start Chat Session

curl -X POST https://api.rachana.com/api/chat \
  -H "Content-Type: application/json" \
  -H "Cookie: supabase-auth-token=..." \
  -d '{
    "message": "What are the current trends in the cryptocurrency market?"
  }'

3. Video Analysis

curl -X POST https://api.rachana.com/api/video-analysis \
  -H "Cookie: supabase-auth-token=..." \
  -F "video=@quarterly_earnings.mp4"

Error Handling Example

Request with Invalid Token:

curl -X POST https://api.rachana.com/api/chat \
  -H "Content-Type: application/json" \
  -H "Cookie: supabase-auth-token=invalid" \
  -d '{"message": "test"}'

Response:

{
  "error": "Invalid authentication token",
  "code": "UNAUTHORIZED"
}

🔒 Security Considerations

Input Validation

  • All inputs are validated for type, length, and format
  • SQL injection protection through parameterized queries
  • XSS prevention with input sanitization
  • File upload restrictions (type, size, content validation)

Authentication Security

  • JWT tokens with short expiration times
  • Secure httpOnly cookies
  • CSRF protection
  • Session management through Supabase

API Security

  • CORS configuration for allowed origins
  • Request size limits
  • Timeout configurations
  • Input sanitization and validation

📚 SDKs and Libraries

JavaScript/TypeScript Client

import { RachanaAPI } from '@rachana/api-client';

const client = new RachanaAPI({
  baseURL: 'https://api.rachana.com',
  credentials: 'include' // For cookie-based auth
});

// Chat with AI
const response = await client.chat.send({
  message: 'Analyze AAPL stock performance'
});

// Analyze video
const analysis = await client.video.analyze({
  file: videoFile
});

Python Client Example

import requests

class RachanaClient:
    def __init__(self, base_url, session_cookies):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.cookies.update(session_cookies)
    
    def chat(self, message):
        response = self.session.post(
            f"{self.base_url}/api/chat",
            json={"message": message}
        )
        return response.json()

This comprehensive API documentation provides complete information for integrating with the Rachana Finance & Technology platform. Each endpoint includes detailed request/response examples, error handling, and security considerations for robust integration.

Need to propose changes? Update docs/API-DOCUMENTATION.md and rerun the build or restart the dev server to refresh this view.