{
  "name": "DSN Research Predictive Analytics API",
  "version": "2.0.0",
  "tagline": "Analytics in Minutes, Not Months",
  "status": "operational",
  "endpoints": {
    "authentication": {
      "POST /api/signup": "Create new account",
      "POST /api/login": "User login",
      "POST /api/logout": "User logout (clears session cookie)",
      "GET /api/verify-email": "Verify email address",
      "POST /api/forgot-password": "Request password reset",
      "POST /api/reset-password": "Reset password with token"
    },
    "payment": {
      "GET /api/payment/methods": "Check available payment methods",
      "POST /api/payment/create-stripe": "Create Stripe checkout session",
      "POST /api/payment/create-paypal": "Create PayPal payment order",
      "GET /api/user/payment/verify": "Verify payment status"
    },
    "user": {
      "GET /api/user/profile": "Get user profile",
      "PUT /api/user/plan": "Update subscription plan",
      "GET /api/user/api-keys": "List all API keys",
      "POST /api/user/api-keys": "Create new API key",
      "POST /api/user/api-keys/revoke": "Revoke API key"
    },
    "data": {
      "POST /api/data/upload": "Upload data (CSV, Excel, JSON, Parquet)",
      "GET /api/data/sources": "List all data sources",
      "GET /api/data/sources/:id": "Get specific data source details",
      "POST /api/data/query": "Query data with SQL-like filters and pagination",
      "POST /api/data/aggregate": "Aggregate a whole source for dashboard widgets (group, histogram, kpi, scatter)"
    },
    "database_connections": {
      "GET /api/data/connections": "List all database connections",
      "POST /api/data/connections": "Create a new database connection (MySQL, PostgreSQL, SQL Server)",
      "GET /api/data/connections/:id": "Get specific connection details",
      "DELETE /api/data/connections/:id": "Delete a database connection",
      "POST /api/data/connections/test": "Test a database connection",
      "GET /api/data/connections/:id/tables": "List tables in connected database",
      "POST /api/data/connections/import": "Import table data as a data source"
    },
    "data_models": {
      "GET /api/data/models": "List all data models",
      "POST /api/data/models": "Create a new data model (star/snowflake schema)",
      "GET /api/data/models/:id": "Get specific data model",
      "PUT /api/data/models/:id": "Update a data model",
      "DELETE /api/data/models/:id": "Delete a data model"
    },
    "analytics": {
      "POST /api/analytics/query": "Create analytics job (async processing)",
      "GET /api/analytics/results/:job_id": "Check analytics job status and results",
      "POST /api/analytics/descriptive": "Get descriptive statistics (mean, median, std, quartiles)",
      "POST /api/analytics/correlation": "Perform correlation analysis between variables",
      "POST /api/analytics/trends": "Analyze trends and patterns over time"
    },
    "models": {
      "POST /api/models/predict": "Generate ML predictions (linear/logistic regression, SVM, time series)",
      "POST /api/models/fraud-detection": "Real-time fraud detection with risk scoring",
      "POST /api/models/churn-prediction": "Customer churn prediction with retention recommendations",
      "POST /api/models/train/linear-regression": "Train linear regression model",
      "POST /api/models/train/logistic-regression": "Train logistic regression model",
      "POST /api/models/train/svm": "Train support vector machine model"
    },
    "advanced_analytics": {
      "POST /api/analytics/clustering": "Perform clustering analysis",
      "POST /api/analytics/anomaly-detection": "Detect anomalies in data",
      "POST /api/analytics/visualizations": "Generate data visualizations"
    },
    "deep_learning": {
      "POST /api/dnn/train": "Train deep neural network for portfolio optimization",
      "POST /api/dnn/predict": "Get optimal portfolio allocation from trained DNN",
      "POST /api/dnn/train-risk-adjusted": "Train DNN with custom risk-aversion parameters",
      "POST /api/dnn/tune": "Automated hyperparameter tuning for DNN models",
      "POST /api/dnn/compare": "Compare multiple DNN models and benchmarks",
      "GET /api/dnn/models": "List all trained DNN models"
    },
    "optimization": {
      "POST /api/optimization/linear": "Solve linear programming problems (maximize/minimize)",
      "GET /api/optimization/templates": "List pre-built optimization templates",
      "GET /api/optimization/templates/:id": "Get specific optimization template with examples",
      "GET /api/optimization/jobs/:job_id": "Check optimization job status and results"
    },
    "ai": {
      "POST /api/ai/chat": "Interactive chat about your data with context awareness",
      "POST /api/ai/completion": "AI-powered text generation and completion",
      "POST /api/ai/sentiment": "Advanced sentiment analysis with aspect-based insights",
      "POST /api/ai/insights": "Generate business insights and recommendations from data"
    },
    "reports": {
      "GET /api/reports": "List previously generated reports (paginated)",
      "GET /api/reports/:id": "Get a specific report with full data",
      "POST /api/reports/generate": "Generate analytics reports (6 types including AI chat analysis)"
    },
    "usage": {
      "GET /api/usage/stats": "Get detailed API usage statistics and rate limit tracking"
    },
    "real_time_analytics": {
      "POST /api/stream/start": "Start real-time data stream",
      "GET /api/stream/:id/connect": "WebSocket connection for stream updates",
      "POST /api/stream/:id/token": "Issue short-lived WebSocket token",
      "POST /api/stream/:id/stop": "Stop stream",
      "POST /api/alerts/configure": "Configure threshold alerts for a stream"
    },
    "agent": {
      "POST /api/agent/execute": "Submit a goal for autonomous multi-step analysis",
      "GET /api/agent/jobs": "List all agent jobs",
      "GET /api/agent/jobs/:id": "Get job status and step details",
      "GET /api/agent/jobs/:id/trace": "Get execution trace/audit log",
      "POST /api/agent/jobs/:id/approve": "Approve a paused job (breakpoint)",
      "POST /api/agent/jobs/:id/cancel": "Cancel a running job"
    },
    "pipelines": {
      "GET /api/pipelines": "List saved native and external pipelines",
      "POST /api/pipelines": "Create a pipeline (ingest → SQL/Python → model/report, or ETL trigger)",
      "POST /api/pipelines/:id/run": "Queue a pipeline run",
      "GET /api/pipelines/:id/runs": "List runs for a pipeline",
      "GET /api/pipelines/connectors": "List Azure Data Factory, Glue, Dataflow, and SnapLogic connectors",
      "POST /api/pipelines/connectors": "Store encrypted ETL credentials and issue a webhook secret",
      "POST /api/webhooks/pipelines/:id": "Resume a waiting external run (HMAC/token)"
    },
    "langgraph": {
      "POST /api/langgraph/agent": "Execute a ReAct agent with full tool access (supports multi-turn via thread_id)",
      "POST /api/langgraph/reflect": "Generate reflection-enhanced insights with iterative quality improvement",
      "POST /api/langgraph/rag": "Agentic RAG: classifies question, retrieves data, grades relevance, runs tools, generates grounded answer",
      "POST /api/langgraph/insights": "Enhanced reflection insights from a data source with critique scoring and tool-assisted deep dives",
      "POST /api/langgraph/supervisor": "Multi-agent supervisor: coordinates data, analysis, ML, and reporting agents for complex goals",
      "POST /api/langgraph/stream/agent": "SSE streaming for ReAct agent execution events",
      "POST /api/langgraph/stream/supervisor": "SSE streaming for supervisor multi-agent execution events",
      "GET /api/langgraph/threads/:threadId": "Retrieve conversation thread state",
      "POST /api/langgraph/verify": "Chain-of-Verification: fact-checks every claim in the answer against your data",
      "POST /api/langgraph/tree-of-thought": "Tree-of-Thought: explores multiple analytical paths and selects the best"
    },
    "genai_enhancements": {
      "POST /api/ai/cag": "Cache-Augmented Generation: answer questions using cached dataset context (faster, cheaper than RAG)",
      "POST /api/mcp": "Model Context Protocol server: expose analytics tools to any MCP-compatible AI client",
      "note_advanced_rag": "The /api/langgraph/rag endpoint now uses Corrective RAG, Self-Adaptive RAG, and HyDE techniques",
      "note_multi_agent_debate": "The /api/langgraph/supervisor can now initiate multi-agent debates when conclusions conflict",
      "note_prompt_guard": "All AI endpoints are protected by PromptGuard — injection and jailbreak detection",
      "note_multi_provider": "Enterprise plans support multi-provider LLM (OpenAI, Gemini, Groq) via the llm-provider abstraction"
    }
  },
  "features": {
    "data_management": [
      "CSV, Excel, JSON upload",
      "SQL-like querying",
      "Multi-source data integration",
      "Automatic schema detection"
    ],
    "analytics": [
      "Descriptive statistics",
      "Correlation analysis",
      "Trend detection",
      "Time series forecasting"
    ],
    "machine_learning": [
      "Linear & logistic regression",
      "Support Vector Machines (SVM)",
      "Fraud detection",
      "Churn prediction",
      "Time series models",
      "K-Means & DBSCAN clustering",
      "Anomaly detection"
    ],
    "deep_learning": [
      "Portfolio optimization DNNs",
      "Risk-adjusted optimization",
      "Hyperparameter tuning",
      "Model comparison",
      "Sharpe ratio maximization",
      "Custom risk-aversion levels"
    ],
    "optimization": [
      "Linear programming solver",
      "Simplex algorithm",
      "Pre-built templates",
      "Production planning",
      "Resource allocation",
      "Portfolio optimization"
    ],
    "ai_services": [
      "Claude-powered chat",
      "Context-aware conversations",
      "Sentiment analysis",
      "Text generation",
      "Business insights",
      "Aspect-based sentiment"
    ]
  },
  "authentication_methods": {
    "api_key": {
      "header": "X-API-Key",
      "format": "dsn_{key_id}_{secret}",
      "description": "Required for data, analytics, ML, DNN, optimization, AI, and usage endpoints",
      "example": "X-API-Key: dsn_abc123_def456..."
    },
    "jwt": {
      "header": "Authorization",
      "format": "Bearer {token}",
      "description": "Required for user management and payment endpoints",
      "example": "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
    }
  },
  "rate_limits": {
    "free": {
      "daily": 100,
      "monthly": 3000,
      "concurrent": 2
    },
    "basic": {
      "daily": 1000,
      "monthly": 30000,
      "concurrent": 5
    },
    "pro": {
      "daily": 10000,
      "monthly": 300000,
      "concurrent": 10
    },
    "premium": {
      "daily": 50000,
      "monthly": 1500000,
      "concurrent": 25
    },
    "enterprise": {
      "daily": "unlimited",
      "monthly": "unlimited",
      "concurrent": 50
    }
  },
  "response_formats": {
    "success": {
      "structure": "{ success: true, data: {...}, metadata: {...} }",
      "http_codes": [
        200,
        201
      ]
    },
    "error": {
      "structure": "{ success: false, error: \"...\", error_code: \"...\", details: {...} }",
      "http_codes": [
        400,
        401,
        403,
        404,
        429,
        500,
        503
      ]
    }
  },
  "getting_started": {
    "step_1": "Sign up: POST /api/signup",
    "step_2": "Verify email: GET /api/verify-email",
    "step_3": "Create API key: POST /api/user/api-keys",
    "step_4": "Upload data: POST /api/data/upload",
    "step_5": "Run analytics: POST /api/analytics/descriptive",
    "step_6": "Train models: POST /api/models/predict or POST /api/dnn/train"
  },
  "use_cases": {
    "financial_services": [
      "Portfolio optimization with DNN",
      "Fraud detection",
      "Risk-adjusted returns",
      "Customer churn prediction"
    ],
    "e_commerce": [
      "Customer sentiment analysis",
      "Sales forecasting",
      "Inventory optimization",
      "Churn prediction"
    ],
    "manufacturing": [
      "Production planning",
      "Resource allocation",
      "Quality control analytics",
      "Predictive maintenance"
    ],
    "healthcare": [
      "Patient outcome prediction",
      "Resource allocation",
      "Trend analysis",
      "Sentiment analysis"
    ]
  },
  "support": {
    "email": "support@dsnresearch.com",
    "documentation": "https://api.dsnresearch.com/docs",
    "website": "https://www.dsnresearch.com"
  },
  "powered_by": {
    "infrastructure": "Cloudflare Workers",
    "database": "Cloudflare D1",
    "ai_models": "Anthropic Claude",
    "optimization": "Simplex Algorithm",
    "deep_learning": "Custom Neural Networks"
  }
}