API Reference

Programmatic access to the Portfolio Optimization platform. Build custom integrations for Indian equities, US equities, and Indian mutual funds, automate optimization workflows, and retrieve results using our REST API.

Base URL

All API endpoints are relative to this base URL

http

https://api.foliolab.ai

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

Quick Navigation

Authentication

Learn about JWT tokens, API keys, and session management

Optimization

Submit jobs for Indian stocks, US stocks, or Indian mutual funds

Jobs

Track job status, view history, and manage artifacts

Results

Retrieve optimization results, metrics, and downloadable reports

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

All 30 runnable 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

Critical Line AlgorithmCriticalLineAlgorithmExact efficient frontier tracing via CLA

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

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

EWMA Mean-VarianceEWMAMVOExponentially weighted moments that adapt to recent volatility

Minimum SemivarianceMinSemivarianceMinimize downside variance while leaving upside variation unpenalized

Minimum EVaRMinEVaRMinimize Entropic Value-at-Risk

Minimum EDaRMinEDaRMinimize Entropic Drawdown-at-Risk

Maximum DecorrelationMaxDecorrelationMinimize the portfolio correlation quadratic form

Robust Mean-VarianceRobustMVOWorst-case MVO under expected-return uncertainty

Resampled Mean-VarianceResampledMVOBootstrap-resampled MVO with averaged portfolio weights

Sparse Index TrackingSparseIndexTrackingTrack a benchmark with a sparse subset of assets

Quintile MomentumQuintileMomentumEqual-weight the highest-momentum asset quintile

Kelly OptimizationKellyLong-only growth-optimal expected log-wealth allocation

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

Indian requests default to the India 10-year government bond series from FRED. US requests must use a US benchmark and set risk_free.region to "US". See the Optimization API for mutual-fund and US-stock schemas, asset discovery endpoints, and complete examples.