InvestAgent API Documentation

Root Routes
Authentication
API Security
Stock Data
Earnings
Forex Data
News
Exchanges
Indices
Treasury
Watchlists
Portfolios
Alerts
Email
Caching
Error Handling

Root Routes

API Documentation (HTML)

Endpoint: GET /

Returns the complete API documentation as a formatted HTML page.

Example:

curl "https://api.investlucid.com/"

Response: Complete HTML documentation page with styling and navigation.

Features: - Interactive HTML documentation - Syntax highlighting for code examples - Responsive design for mobile devices - Table of contents with anchor links - Method badges (GET, POST, PUT, DELETE)

API Information (JSON)

Endpoint: GET /api

Returns server status and available endpoints in JSON format.

Example:

curl "https://api.investlucid.com/api"

Response:

{
  "status": "success",
  "message": "InvestAgent server is running",
  "version": "0.1.0",
  "documentation": "Visit / for full HTML documentation",
  "endpoints": {
    "stocks": {
      "price": "/api/stock/price/<symbols>?symbols=<symbols>&long=<true|false>",
      "price_bulk": "/api/stock/price/bulk?symbols=<symbols>",
      "aftermarket_prices": "/api/stock/after-market-price?symbols=<symbols>",
      "historical": "/api/stock/historical/<symbol>",
      "historical_light": "/api/stock/historical-light/<symbol>",
      "historical_chart_5min": "/api/stock/historical-chart/5min/<symbol>?from_date=<YYYY-MM-DD>&to_date=<YYYY-MM-DD>",
      "profile": "/api/stock/profile/<symbol>",
      "financials": "/api/stock/financials/<symbol>?type=<income|balance-sheet|cash-flow>&limit=<1-50>&period=<Q1|Q2|Q3|Q4|FY>",
      "aftermarket_quote": "/api/stock/aftermarket-quote/<symbol>",
      "price_change": "/api/stock/price-change/<symbol>",
      "ratings": "/api/stock/ratings/<symbol>",
      "list": "/api/stock/list/<exchanges>"
    },
    "earnings": {
      "calendar": "/api/earnings"
    },
    "forex": {
      "quote": "/api/forex/quote/<symbol>?long=<true|false>",
      "quotes": "/api/forex/quotes?pairs=<pairs>&long=<true|false>",
      "historical": "/api/forex/historical/<symbol>"
    },
    "news": {
      "latest": "/api/news/latest?page=<page>&limit=<limit>",
      "stock_news": "/api/news/stock/<symbols>?page=<page>&limit=<limit>",
      "press_releases": "/api/news/press-releases?page=<page>&limit=<limit>"
    },
    "exchanges": {
      "hours": "/api/exchange/hours/<exchange>",
      "all_hours": "/api/exchange/hours",
      "list": "/api/exchanges",
      "exchanges_list": "/api/exchanges/list"
    },
    "indices": {
      "constituents": "/api/index/constituents/<index_name>?format=<json|csv>&include_metadata=<true|false>"
    },
    "treasury": {
      "rates": "/api/treasury/rates?from_date=<YYYY-MM-DD>&to_date=<YYYY-MM-DD>"
    },
    "auth": {
      "login": "/api/auth/login",
      "user": "/api/auth/user/<user_id>",
      "logout": "/api/auth/logout"
    },
    "watchlists": {
      "get_all_watchlists": "/api/watchlists/<user_id>",
      "create_watchlist": "/api/watchlists/<user_id> (POST)",
      "get_watchlist": "/api/watchlist/<user_id>/<watchlist_id>",
      "update_watchlist": "/api/watchlist/<user_id>/<watchlist_id> (POST)",
      "delete_watchlist": "/api/watchlist/<user_id>/<watchlist_id> (DELETE)"
    },
    "portfolios": {
      "get_all_portfolios": "/api/portfolios/<user_id>",
      "create_portfolio": "/api/portfolios/<user_id> (POST)",
      "edit_portfolio": "/api/portfolios/<user_id>/<portfolio_id> (PUT)",
      "delete_portfolio": "/api/portfolios/<user_id>/<portfolio_id> (DELETE)",
      "add_update_stock": "/api/portfolios/<user_id>/<portfolio_id>/stock (POST) - Supports single stock or bulk operations",
      "remove_stock": "/api/portfolios/<user_id>/<portfolio_id>/stock/<symbol> (DELETE)"
    },
    "alerts": {
      "get_alerts": "/api/alerts/<user_id>",
      "add_alert": "/api/alerts/<user_id> (POST)",
      "update_alert": "/api/alerts/<user_id>/<alert_type>/<symbol> (PUT)",
      "delete_alert": "/api/alerts/<user_id>/<alert_type>/<symbol> (DELETE)",
      "delete_all_alerts": "/api/alerts/<user_id> (DELETE)"
    },
    "email": {
      "send_portfolio_summary": "/api/email/portfolio-summary/<user_id> (POST)"
    },
    "dividends": {
      "stock_dividends": "/api/stock/dividend/<symbol>"
    }
  },
  "example": "Try /api/stock/price/AAPL for Apple stock price"
}

Use Cases: - API Discovery: Get an overview of all available endpoints - Health Check: Verify the server is running - Version Information: Check the current API version - Quick Reference: Get endpoint URLs for programmatic use

Authentication

InvestAgent uses JWT (JSON Web Token) based authentication with Google OAuth integration. All user-specific endpoints require valid JWT tokens.

Endpoint: POST /api/auth/login

Authenticate a user using Google OAuth and return JWT tokens.

Request Body:

{
  "user": {
    "id": "google_user_id",
    "email": "user@gmail.com",
    "name": "John Doe",
    "picture": "https://lh3.googleusercontent.com/..."
  },
  "token": "google_id_token"
}

Response:

{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "google_user_id",
    "email": "user@gmail.com",
    "name": "John Doe",
    "picture": "https://lh3.googleusercontent.com/..."
  },
  "tokens": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400
  }
}

Get User Profile

Endpoint: GET /api/auth/user/<user_id>

Get user information by ID (requires authentication).

Headers:

Authorization: Bearer <access_token>

Response:

{
  "success": true,
  "user": {
    "id": "google_user_id",
    "email": "user@gmail.com",
    "name": "John Doe"
  }
}

Logout

Endpoint: POST /api/auth/logout

Log out the current user.

Response:

{
  "success": true,
  "message": "Logout successful"
}

API Security

Authentication Requirements

Protected Endpoints (Require JWT Token): - All user-specific data: /api/portfolios/*, /api/watchlists/*, /api/alerts/*, /api/email/* - User profile: /api/auth/user/*

Public Endpoints (No Authentication Required): - Market data: /api/stock/*, /api/forex/*, /api/index/*, /api/treasury/* - News: /api/news/* - Exchanges: /api/exchange/* - Earnings: /api/earnings

Using JWT Tokens

Include the JWT token in the Authorization header for all protected endpoints:

curl -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/portfolios/user123"

Token Expiration

Access Token: 24 hours
Refresh Token: 30 days
Tokens are automatically refreshed by the frontend when needed

Error Responses

401 Unauthorized:

{
  "error": "Authentication required",
  "message": "Valid JWT token is required",
  "code": "AUTH_REQUIRED"
}

403 Forbidden:

{
  "error": "Access denied",
  "message": "You can only access your own data"
}

Stock Data

Stock Price

Endpoint: GET /api/stock/price/<symbol>

Get current stock price for a single symbol or multiple symbols.

Query Parameters: - symbols (optional): Comma-separated list of additional symbols - long (optional): If true, returns detailed quote (default: false)

Example:

curl "https://api.investlucid.com/api/stock/price/AAPL"
curl "https://api.investlucid.com/api/stock/price/AAPL?symbols=MSFT,GOOGL&long=true"

Response: Array of stock price objects for all requested symbols.

Bulk Stock Prices

Endpoint: GET /api/stock/price/bulk?symbols=<symbol_list>

Get current stock prices for multiple symbols at once using the FMP bulk API.

Parameters: - symbols (required): Comma-separated list of stock symbols

Example:

curl "https://api.investlucid.com/api/stock/price/bulk?symbols=AAPL,MSFT,GOOGL,TSLA"

Response: Array of stock price objects for all requested symbols.

Historical Prices

Endpoint: GET /api/stock/historical/<symbol>

Get historical stock prices for a given symbol.

Query Parameters: - from_date (optional): Start date (YYYY-MM-DD) - to_date (optional): End date (YYYY-MM-DD) - timeframe (optional): '1day' (default)

Example:

curl "https://api.investlucid.com/api/stock/historical/AAPL?from_date=2024-01-01&to_date=2024-06-01"

Response: Array of historical price objects.

Historical Prices (Light)

Endpoint: GET /api/stock/historical-light/<symbol>

Get lightweight historical stock prices for a given symbol.

Example:

curl "https://api.investlucid.com/api/stock/historical-light/AAPL"

Response: Array of historical price objects (lightweight version).

5-Minute Historical Chart

Endpoint: GET /api/stock/historical-chart/5min/<symbol>

Get 5-minute historical chart data for a given symbol.

Query Parameters: - from_date (optional): Start date (YYYY-MM-DD) - to_date (optional): End date (YYYY-MM-DD)

Example:

curl "https://api.investlucid.com/api/stock/historical-chart/5min/AAPL?from_date=2024-06-01"

Response: Array of 5-min OHLCV data.

Stock Profile

Endpoint: GET /api/stock/profile/<symbol>

Get company profile information for a given symbol.

Example:

curl "https://api.investlucid.com/api/stock/profile/AAPL"

Response: Profile object for the symbol.

Financials

Endpoint: GET /api/stock/financials/<symbol>

Get financial statements for a given symbol.

Query Parameters: - type (optional): income, balance-sheet, cash-flow (default: income) - limit (optional): Number of records (1-50, default: 5) - period (optional): Q1, Q2, Q3, Q4, FY

Example:

curl "https://api.investlucid.com/api/stock/financials/AAPL?type=income&limit=3&period=Q1"

Response: Financial statement(s) for the symbol.

Aftermarket Quote

Endpoint: GET /api/stock/aftermarket-quote/<symbol>

Get after-hours bid/ask and volume data for a single stock.

Example:

curl "https://api.investlucid.com/api/stock/aftermarket-quote/AAPL"

Response: Aftermarket quote object with bid/ask prices and volume.

Aftermarket Prices (Bulk)

Endpoint: GET /api/stock/after-market-price

Get aftermarket prices for multiple symbols in parallel with smart caching.

Query Parameters: - symbols (required): Comma-separated list of stock symbols (e.g., 'AAPL,NVDA,MSFT')

Example:

curl "https://api.investlucid.com/api/stock/after-market-price?symbols=AAPL,NVDA"
curl "https://api.investlucid.com/api/stock/after-market-price?symbols=AAPL,NVDA,MSFT,GOOGL"

Response: Array of aftermarket price objects for all requested symbols.

Features: - Parallel fetching using threads for improved performance - Smart caching based on market hours (10 seconds during extended hours, longer outside) - Individual caching for each symbol - Automatic deduplication of symbols - Returns results in the same order as requested

Response Example:

[
  {
    "symbol": "AAPL",
    "price": 201.28,
    "timestamp": 1750982398000,
    "tradeSize": 80
  },
  {
    "symbol": "NVDA",
    "price": 155.35,
    "timestamp": 1750982398000,
    "tradeSize": null
  }
]

Caching Strategy: - During extended hours (2 hours before market open to 2 hours after market close): Cache for 10 seconds - Outside extended hours: Cache until 2 hours before next market open - Uses NASDAQ market hours for calculations

Stock Price Change

Endpoint: GET /api/stock/price-change/<symbol>

Get price change percentages for various periods (1D, 5D, 1M, 3M, 6M, 1Y, 3Y, 5Y, 10Y, YTD, max).

Example:

curl "https://api.investlucid.com/api/stock/price-change/AAPL"

Response:

[
  {
    "symbol": "AAPL",
    "1D": 2.25,
    "5D": 1.87,
    "1M": -0.54,
    "3M": -7.91,
    "6M": -21.02,
    "1Y": -3.13,
    "3Y": 47.93,
    "5Y": 124.03,
    "10Y": 530.09,
    "ytd": -17.57,
    "max": 156503.04
  }
]

Stock Dividends

Endpoint: GET /api/stock/dividend/<symbol>

Get dividend history for a given stock symbol. Returns only record date and adjusted dividend amount. Data is cached for 7 days.

Example:

curl "https://api.investlucid.com/api/stock/dividend/AAPL"

Response:

[
  {
    "recordDate": "2025-05-12",
    "adjDividend": 0.26
  },
  {
    "recordDate": "2025-02-10",
    "adjDividend": 0.25
  },
  {
    "recordDate": "2024-11-08",
    "adjDividend": 0.25
  }
]

Stock List

Endpoint: GET /api/stock/list/<exchanges>

Get list of stocks for one or more exchanges (e.g., NASDAQ, NYSE).

Example:

curl "https://api.investlucid.com/api/stock/list/NASDAQ,NYSE"

Response: List of stocks per exchange.

Stock Ratings & Price Targets

Endpoint: GET /api/stock/ratings/<symbol>

Get price targets and analyst consensus ratings for a given stock symbol. Data is cached for 1 day (24 hours).

Example:

curl "https://api.investlucid.com/api/stock/ratings/AAPL"

Response:

{
  "symbol": "AAPL",
  "ratings": {
    "price_targets": [
      {
        "symbol": "AAPL",
        "publishedDate": "2025-07-03T13:31:00.000Z",
        "newsURL": "https://www.streetinsider.com/Analyst+Comments/UBS+Reiterates+Neutral+Rating+on+Apple+%28AAPL%29%2C+Sees+Limited+Impact+From+Vietnam+Trade+Deal/25015424.html",
        "newsTitle": "UBS Reiterates Neutral Rating on Apple (AAPL), Sees Limited Impact From Vietnam Trade Deal",
        "analystName": "David Vogt",
        "priceTarget": 210,
        "adjPriceTarget": 210,
        "priceWhenPosted": 214.33,
        "newsPublisher": "StreetInsider",
        "newsBaseURL": "streetinsider.com",
        "analystCompany": "UBS"
      }
    ],
    "count": 50
  },
  "recommendations": [
    {
      "symbol": "AAPL",
      "strongBuy": 1,
      "buy": 72,
      "hold": 29,
      "sell": 7,
      "strongSell": 0,
      "consensus": "Buy"
    }
  ]
}

Features: - Returns up to 50 most recent price targets - Includes analyst information and news sources - Provides analyst consensus breakdown (Strong Buy, Buy, Hold, Sell, Strong Sell) - Shows overall consensus recommendation - Data cached for 24 hours for optimal performance - Comprehensive price target history with publication dates - Links to original news articles and analyst reports

Response Fields:

Price Targets (ratings.price_targets): - symbol: Stock symbol - publishedDate: Date when the rating was published (ISO 8601 format) - newsURL: URL to the original news article - newsTitle: Title of the news article - analystName: Name of the analyst (may be empty) - priceTarget: Price target value - adjPriceTarget: Adjusted price target value - priceWhenPosted: Stock price when the target was posted - newsPublisher: Publisher of the news article - newsBaseURL: Base URL of the news source - analystCompany: Company/firm of the analyst

Analyst Consensus (recommendations): - symbol: Stock symbol - strongBuy: Number of Strong Buy recommendations - buy: Number of Buy recommendations - hold: Number of Hold recommendations - sell: Number of Sell recommendations - strongSell: Number of Strong Sell recommendations - consensus: Overall consensus recommendation (e.g., "Buy", "Hold", "Sell")

Earnings

Earnings Calendar

Endpoint: GET /api/earnings

Get earnings data organized by date for NASDAQ, NYSE, and AMEX exchanges. Returns data from current date - 1 to current date + 15.

Example:

curl "https://api.investlucid.com/api/earnings"

Response:

{
  "2025-06-26": [
    {
      "exchange": "NASDAQ",
      "symbol": "NAAS"
    },
    {
      "epsActual": 0.23,
      "epsEstimated": 0.08,
      "exchange": "NASDAQ",
      "revenueActual": 60875000.0,
      "revenueEstimated": 106192500.0,
      "symbol": "TTGT"
    }
  ],
  "2025-06-27": [
    {
      "exchange": "NYSE",
      "symbol": "AAPL",
      "epsEstimated": 1.45,
      "revenueEstimated": 85000000000.0
    }
  ]
}

Features: - Data organized by date for easy access - Includes actual and estimated EPS and revenue data - Filters for major exchanges (NASDAQ, NYSE, AMEX) - Covers 16-day range around current date - NaN values are filtered out for clean JSON

Forex Data

Forex Quote

Endpoint: GET /api/forex/quote/<symbol>

Get current forex quote for a currency pair.

Query Parameters: - long (optional): If true, returns detailed quote (default: false)

Example:

curl "https://api.investlucid.com/api/forex/quote/EURUSD?long=true"

Response: Forex quote object.

Forex Quotes (Bulk)

Endpoint: GET /api/forex/quotes

Get current forex quotes for multiple currency pairs in parallel.

Query Parameters: - pairs (required): Comma-separated list of forex symbols (e.g., 'EURUSD,GBPUSD,USDJPY') - long (optional): If true, returns detailed quotes; else returns short quotes (default: false)

Example:

curl "https://api.investlucid.com/api/forex/quotes?pairs=EURUSD,GBPUSD,USDJPY"
curl "https://api.investlucid.com/api/forex/quotes?pairs=EURUSD,GBPUSD&long=true"

Response: Array of forex quote objects for all requested pairs.

Features: - Parallel processing for improved performance - Automatic deduplication of currency pairs - Returns results in the same order as requested - Supports both short and detailed quote formats

Forex Historical

Endpoint: GET /api/forex/historical/<symbol>

Get historical forex data for a given symbol.

Query Parameters: - from_date (optional): Start date (YYYY-MM-DD) - to_date (optional): End date (YYYY-MM-DD) - timeframe (optional): '1day' (default)

Example:

curl "https://api.investlucid.com/api/forex/historical/EURUSD?from_date=2024-01-01&to_date=2024-06-01"

Response: Array of historical forex data.

News

Latest News

Endpoint: GET /api/news/latest

Get latest financial news articles.

Query Parameters: - page (optional): Page number (default: 0) - limit (optional): Number of articles per page (default: 20, max: 50)

Example:

curl "https://api.investlucid.com/api/news/latest?page=0&limit=10"

Response: Array of latest news articles.

Press Releases

Endpoint: GET /api/news/press-releases

Get latest press releases.

Query Parameters: - page (optional): Page number (default: 0) - limit (optional): Number of press releases per page (default: 20, max: 50)

Example:

curl "https://api.investlucid.com/api/news/press-releases?page=0&limit=10"

Response: Array of press release articles.

Stock News

Endpoint: GET /api/news/stock/<symbols>

Get latest news for one or more stock symbols. <symbols> can be a single symbol (e.g., AAPL) or a comma-separated list (e.g., AAPL,MSFT,GOOGL).

Query Parameters: - page (optional): Page number (default: 0) - limit (optional): Number of news articles per symbol (default: 20, max: 50)

Example:

curl "https://api.investlucid.com/api/news/stock/AAPL?page=0&limit=5"
curl "https://api.investlucid.com/api/news/stock/AAPL,MSFT,GOOGL?page=0&limit=5"

Response: Array of news articles, each with a symbol field indicating the associated ticker.

Exchanges

Exchange Hours

Endpoint: GET /api/exchange/hours/<exchange>

Get trading hours for a specific exchange.

Example:

curl "https://api.investlucid.com/api/exchange/hours/NASDAQ"

Response: Exchange hours object.

All Exchange Hours

Endpoint: GET /api/exchange/hours

Get trading hours for all exchanges.

Example:

curl "https://api.investlucid.com/api/exchange/hours"

Response: Object with hours for all exchanges.

Available Exchanges

Endpoint: GET /api/exchanges

Get list of available exchanges.

Example:

curl "https://api.investlucid.com/api/exchanges"

Response: Array of available exchanges.

Exchanges List

Endpoint: GET /api/exchanges/list

Get detailed list of exchanges with additional information.

Example:

curl "https://api.investlucid.com/api/exchanges/list"

Response: Array of exchanges with detailed information.

Indices

Index Constituents

Endpoint: GET /api/index/constituents/<index_name>

Get constituents of a market index (e.g., SP500, NASDAQ, DJI).

Query Parameters: - format (optional): Output format - 'json' or 'csv' (default: 'json') - include_metadata (optional): Include additional metadata - 'true' or 'false' (default: 'false')

Example:

curl "https://api.investlucid.com/api/index/constituents/SP500"
curl "https://api.investlucid.com/api/index/constituents/SP500?format=csv"
curl "https://api.investlucid.com/api/index/constituents/SP500?include_metadata=true"

Response: Array of index constituents or CSV data.

Treasury

Treasury Rates

Endpoint: GET /api/treasury/rates

Get treasury rates data.

Query Parameters: - from_date (optional): Start date (YYYY-MM-DD) - to_date (optional): End date (YYYY-MM-DD)

Example:

curl "https://api.investlucid.com/api/treasury/rates?from_date=2024-01-01&to_date=2024-06-01"

Response: Array of treasury rates data.

Watchlists

⚠️ Authentication Required: All watchlist endpoints require a valid JWT token.

Get All Watchlists

Endpoint: GET /api/watchlists/<user_id>

Get all watchlists (id and name) for a user.

Headers:

Authorization: Bearer <access_token>

Example:

curl -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/watchlists/user123"

Response:

{
  "success": true,
  "watchlists": [
    {
      "id": 1,
      "name": "Tech Stocks"
    },
    {
      "id": 2,
      "name": "Dividend Stocks"
    }
  ]
}

Create Watchlist

Endpoint: POST /api/watchlists/<user_id>

Create a new watchlist for a user.

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body:

{
  "name": "New Watchlist"
}

Response:

{
  "success": true,
  "watchlist": {
    "id": 3,
    "name": "New Watchlist",
    "tickers": []
  }
}

Get Watchlist Details

Endpoint: GET /api/watchlist/<user_id>/<watchlist_id>

Get a specific watchlist's details, including ticker prices.

Headers:

Authorization: Bearer <access_token>

Example:

curl -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/watchlist/user123/1"

Response:

{
  "success": true,
  "watchlist": {
    "id": 1,
    "name": "Tech Stocks",
    "tickers": [
      {
        "symbol": "AAPL",
        "name": "Apple Inc.",
        "price": 201.28,
        "change": 2.15,
        "changePercent": 1.08
      },
      {
        "symbol": "MSFT",
        "name": "Microsoft Corporation",
        "price": 415.50,
        "change": -1.20,
        "changePercent": -0.29
      }
    ]
  }
}

Update Watchlist

Endpoint: POST /api/watchlist/<user_id>/<watchlist_id>

Update tickers for a specific watchlist.

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body:

{
  "tickers": ["AAPL", "MSFT", "GOOGL", "TSLA"]
}

Response: Updated watchlist with current prices.

Delete Watchlist

Endpoint: DELETE /api/watchlist/<user_id>/<watchlist_id>

Delete a specific watchlist.

Headers:

Authorization: Bearer <access_token>

Example:

curl -X DELETE \
     -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/watchlist/user123/1"

Response:

{
  "success": true,
  "message": "Watchlist deleted successfully"
}

Portfolios

⚠️ Authentication Required: All portfolio endpoints require a valid JWT token.

List Portfolios

Endpoint: GET /api/portfolios/<user_id>

Get all portfolios for a user.

Headers:

Authorization: Bearer <access_token>

Example:

curl -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/portfolios/user123"

Response:

[
  {
    "id": 1,
    "name": "Growth Portfolio",
    "stocks": [
      {
        "symbol": "AAPL",
        "quantity": 10,
        "total_cost": 1500.00
      }
    ]
  }
]

Create Portfolio

Endpoint: POST /api/portfolios/<user_id>

Create a new portfolio for a user.

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body:

{
  "name": "Tech Portfolio"
}

Response:

{
  "id": 3,
  "name": "Tech Portfolio",
  "stocks": []
}

Edit Portfolio

Endpoint: PUT /api/portfolios/<user_id>/<portfolio_id>

Edit a portfolio's name.

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body:

{
  "name": "Updated Portfolio Name"
}

Response:

{
  "id": 1,
  "name": "Updated Portfolio Name",
  "stocks": [...]
}

Delete Portfolio

Endpoint: DELETE /api/portfolios/<user_id>/<portfolio_id>

Delete a portfolio.

Headers:

Authorization: Bearer <access_token>

Example:

curl -X DELETE \
     -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/portfolios/user123/1"

Response:

{
  "success": true
}

Add/Update Stock(s)

Endpoint: POST /api/portfolios/<user_id>/<portfolio_id>/stock

Add or update stock(s) in a portfolio. Supports both single stock and bulk operations.

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Single Stock Operation

Request Body:

{
  "symbol": "AAPL",
  "quantity": 10,
  "total_cost": 1500.00
}

Bulk Stock Operation (Multiple Stocks)

Request Body:

{
  "stocks": [
    {
      "symbol": "AAPL",
      "quantity": 10,
      "total_cost": 1500.00
    },
    {
      "symbol": "MSFT",
      "quantity": 5,
      "total_cost": 1200.00
    },
    {
      "symbol": "GOOGL",
      "quantity": 2,
      "total_cost": 800.00
    }
  ]
}

Response:

{
  "success": true,
  "message": "Successfully processed 3 stock(s)",
  "portfolio": {
    "id": 1,
    "name": "Growth Portfolio",
    "stocks": [
      {
        "symbol": "AAPL",
        "quantity": 10,
        "total_cost": 1500.00
      },
      {
        "symbol": "MSFT",
        "quantity": 5,
        "total_cost": 1200.00
      },
      {
        "symbol": "GOOGL",
        "quantity": 2,
        "total_cost": 800.00
      }
    ]
  }
}

Notes: - If a stock already exists in the portfolio, it will be updated with new quantity and total_cost - If a stock doesn't exist, it will be added to the portfolio - Stock symbols are automatically normalized to uppercase - Validates that quantity and total_cost are valid numbers - Provides detailed error messages for validation failures

Remove Stock

Endpoint: DELETE /api/portfolios/<user_id>/<portfolio_id>/stock/<symbol>

Remove a stock from a portfolio.

Headers:

Authorization: Bearer <access_token>

Example:

curl -X DELETE \
     -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/portfolios/user123/1/stock/AAPL"

Response:

{
  "message": "Stock AAPL removed from portfolio"
}

Alerts

⚠️ Authentication Required: All alert endpoints require a valid JWT token.

Get All Alerts

Endpoint: GET /api/alerts/<user_id>

Get all alerts for a user.

Headers:

Authorization: Bearer <access_token>

Example:

curl -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/alerts/user123"

Response:

{
  "buy": [
    {
      "symbol": "AAPL",
      "price": 150.00,
      "created_at": "2025-06-23T18:09:57.835095"
    }
  ],
  "sell": [
    {
      "symbol": "MSFT",
      "price": 450.00,
      "created_at": "2025-06-23T18:10:15.123456"
    }
  ]
}

Create Alert

Endpoint: POST /api/alerts/<user_id>

Create a new alert for a user.

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body:

{
  "type": "buy",
  "symbol": "AAPL",
  "price": 150.00
}

Response:

{
  "symbol": "AAPL",
  "price": 150.00,
  "created_at": "2025-06-23T18:09:57.835095"
}

Update Alert

Endpoint: PUT /api/alerts/<user_id>/<alert_type>/<symbol>

Update an existing alert's price.

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body:

{
  "price": 155.00
}

Response:

{
  "symbol": "AAPL",
  "price": 155.00,
  "created_at": "2025-06-23T18:09:57.835095",
  "updated_at": "2025-06-23T18:15:30.123456"
}

Delete Alert

Endpoint: DELETE /api/alerts/<user_id>/<alert_type>/<symbol>

Delete an alert for a user.

Headers:

Authorization: Bearer <access_token>

Example:

curl -X DELETE \
     -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/alerts/user123/buy/AAPL"

Response:

{
  "message": "Alert for AAPL deleted successfully"
}

Delete All Alerts

Endpoint: DELETE /api/alerts/<user_id>

Delete all alerts for a user, optionally by type.

Headers:

Authorization: Bearer <access_token>

Query Parameters: - type (optional): 'buy' or 'sell' to delete only that type

Example:

# Delete all alerts
curl -X DELETE \
     -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/alerts/user123"

# Delete only buy alerts
curl -X DELETE \
     -H "Authorization: Bearer <your_jwt_token>" \
     "https://api.investlucid.com/api/alerts/user123?type=buy"

Response:

{
  "message": "All alerts deleted successfully"
}

Email

⚠️ Authentication Required: All email endpoints require a valid JWT token.

Send Portfolio Summary Email

Endpoint: POST /api/email/portfolio-summary/<user_id>

Send portfolio summary email to user.

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Response:

{
  "success": true,
  "message": "Portfolio summary email sent successfully"
}

Caching

Redis Caching Strategy

InvestAgent uses Redis for intelligent caching with different strategies:

Market Data Caching: - Stock prices: 30 seconds during market hours, 5 minutes outside - Historical data: 1 hour - Financial data: 24 hours - News: 15 minutes

User Data Caching: - User profiles: 5 minutes - Portfolios: Bypassed on write operations - Watchlists: Bypassed on write operations - Alerts: Bypassed on write operations

Aftermarket Data Caching: - During extended hours: 10 seconds - Outside extended hours: Until next market open

Cache Invalidation

User data is automatically invalidated on write operations
Market data expires based on configured TTL
Manual cache clearing available for debugging

Error Handling

Standard Error Responses

400 Bad Request:

{
  "error": "Invalid request",
  "message": "Missing required field: symbol"
}

401 Unauthorized:

{
  "error": "Authentication required",
  "message": "Valid JWT token is required",
  "code": "AUTH_REQUIRED"
}

403 Forbidden:

{
  "error": "Access denied",
  "message": "You can only access your own data"
}

404 Not Found:

{
  "error": "Resource not found",
  "message": "Portfolio not found"
}

500 Internal Server Error:

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

Rate Limiting

Public endpoints: 100 requests per minute per IP
Authenticated endpoints: 1000 requests per minute per user
Bulk endpoints: 50 requests per minute per user

API Versioning

Current API version: v1 - All endpoints are prefixed with /api/ - Backward compatibility maintained for public endpoints - Breaking changes will be communicated in advance

/api/index/stock-prices/

Returns a CSV with symbol, name, current price, change, change %, sector, subsector, founded, headQuarter for all index constituents. Example: /api/index/stock-prices/SP500

InvestAgent API Documentation

InvestAgent API Documentation

Table of Contents

Root Routes

API Documentation (HTML)

API Information (JSON)

Authentication

Google OAuth Login

Get User Profile

Logout

API Security

Authentication Requirements

Using JWT Tokens

Token Expiration

Error Responses

Stock Data

Stock Price

Bulk Stock Prices

Historical Prices

Historical Prices (Light)

5-Minute Historical Chart

Stock Profile

Financials

Aftermarket Quote

Aftermarket Prices (Bulk)

Stock Price Change

Stock Dividends

Stock List

Stock Ratings & Price Targets

Earnings

Earnings Calendar

Forex Data

Forex Quote

Forex Quotes (Bulk)

Forex Historical

News

Latest News

Press Releases

Stock News

Exchanges

Exchange Hours

All Exchange Hours

Available Exchanges

Exchanges List

Indices

Index Constituents

Treasury

Treasury Rates

Watchlists

Get All Watchlists

Create Watchlist

Get Watchlist Details

Update Watchlist

Delete Watchlist

Portfolios

List Portfolios

Create Portfolio

Edit Portfolio

Delete Portfolio

Add/Update Stock(s)

Single Stock Operation

Bulk Stock Operation (Multiple Stocks)

Remove Stock

Alerts

Get All Alerts

Create Alert

Update Alert

Delete Alert

Delete All Alerts

Email

Send Portfolio Summary Email

Caching

Redis Caching Strategy

Cache Invalidation

Error Handling

Standard Error Responses

Rate Limiting

API Versioning

/api/index/stock-prices/