Folio Lab/Documentation

API Reference

Programmatic access to the Portfolio Optimization platform. Build custom integrations, automate optimization workflows, and retrieve results using our REST API.

Base URL

All API endpoints are relative to this base URL

http
https://api.portfolioopt.in

All requests must be made over HTTPS. HTTP requests will be rejected.

Authentication Overview

Two authentication methods are supported depending on your use case

JWT Tokens

Best for web applications and interactive use. Tokens are issued via login and automatically refreshed using secure HTTP-only cookies.

Web / Interactive

API Keys

Best for server-to-server communication, scripts, and CI/CD pipelines. Scoped keys with fine-grained permissions.

Programmatic / Server

See the Authentication page for complete details on sign-up, login, token refresh, API key creation, and security best practices.

Rate Limiting

Fair-use limits to ensure platform stability for all users

Endpoint CategoryRate Limit
Authentication endpoints10 req/min
Optimization submissions20 req/min
Job status & results60 req/min
Report downloads (Excel/PDF)30 req/min

When a rate limit is exceeded, the API responds with HTTP 429 Too Many Requests. The Retry-After header indicates how many seconds to wait before retrying.

Error Response Format

All error responses follow a consistent JSON structure

When an API request fails, the response body contains a JSON object with a human-readable error message:

json
{
  "detail": "Human-readable error message"
}

HTTP Status Codes

CodeStatusDescription
400Bad RequestThe request body is malformed or missing required fields
401UnauthorizedMissing or invalid authentication credentials
403ForbiddenValid credentials but insufficient permissions for the resource
404Not FoundThe requested resource does not exist
409ConflictThe request conflicts with the current state (e.g., duplicate email)
500Internal Server ErrorAn unexpected server-side error occurred

Supported Optimization Methods

Pass these enum values in the methods array when submitting an optimization job

MethodAPI ValueDescription
Mean-Variance OptimizationMVOClassic Markowitz mean-variance portfolio optimization
Minimum VolatilityMinVolMinimize portfolio volatility regardless of returns
Max Quadratic UtilityMaxQuadraticUtilityMaximize risk-adjusted utility with quadratic penalty
Equal WeightedEquiWeightedUniform allocation across all selected assets
Hierarchical Risk ParityHRPTree-based clustering for robust diversification
Minimum CVaRMinCVaRMinimize Conditional Value-at-Risk (expected shortfall)
Minimum CDaRMinCDaRMinimize Conditional Drawdown-at-Risk
HERCHERCHierarchical Equal Risk Contribution
NCONCONested Clustered Optimization
HERC2HERC2Enhanced Hierarchical Equal Risk Contribution
Critical Line AlgorithmCriticalLineAlgorithmExact efficient frontier tracing via CLA
Benchmark TrackerBenchmarkTrackerMinimize tracking error to a benchmark index
Maximum DiversificationMaximumDiversificationMaximize the portfolio diversification ratio
Risk BudgetingRiskBudgetingTarget equal or custom risk contribution per asset
Distributionally Robust CVaRDistributionallyRobustCVaRWorst-case CVaR over Wasserstein uncertainty set
Stacking OptimizationStackingOptimizationEnsemble meta-optimizer stacking multiple sub-models
Inverse VolatilityInverseVolatilityWeights inversely proportional to each asset's volatility
Sparse Markowitz (L1)SparseMarkowitzL1L1-regularized Markowitz for sparse, concentrated portfolios
HMM Regime MVOHMMRegimeMVOHidden Markov Model regime-switching mean-variance
Black-LittermanBlackLittermanBlack-Litterman with market-implied equilibrium returns and momentum views

Example usage in request body:

json
{
  "stocks": [
    { "ticker": "RELIANCE", "exchange": "NSE" },
    { "ticker": "TCS", "exchange": "NSE" },
    { "ticker": "HDFCBANK", "exchange": "NSE" },
    { "ticker": "INFY", "exchange": "NSE" }
  ],
  "methods": ["MVO", "HRP", "MinCVaR"],
  "benchmark": "nifty"
}

The risk-free rate is automatically sourced from India 10-year government bond yields and does not need to be specified in the request.