diff --git a/api-reference/auth.mdx b/api-reference/auth.mdx index 04e47e0..b9b8b42 100644 --- a/api-reference/auth.mdx +++ b/api-reference/auth.mdx @@ -135,7 +135,3 @@ Only users with email addresses in this list can access the application after au OAuth tokens are never exposed to the client - -## Configuration - -See the [SSO Setup Guide](/guides/setup/sso) for detailed configuration instructions. diff --git a/api-reference/calendar.mdx b/api-reference/calendar.mdx new file mode 100644 index 0000000..a3936f3 --- /dev/null +++ b/api-reference/calendar.mdx @@ -0,0 +1,230 @@ +--- +title: 'Calendar Data Endpoints' +description: 'Trading calendar and daily activity tracking endpoints' +--- + +## Get Calendar Data + +``` +GET /api/calendar-data +``` + +Retrieves daily trading activity data for calendar view including weekly aggregates. + +**Query Parameters:** +- `year` (number, optional): Year to display (defaults to current year) +- `month` (number, optional): Month to display 1-12 (defaults to current month) + +**Example:** +```http +GET /api/calendar-data?year=2024&month=8 +``` + +**Response:** +```json +{ + "success": true, + "year": 2024, + "month": 8, + "days": [ + { + "date": "2024-08-01", + "day": 1, + "day_of_week": 4, + "trade_count": 3, + "trading_pnl": 150.25, + "dividend_count": 0, + "dividends": 0, + "total_pnl": 150.25, + "has_activity": true, + "week_trade_count": 12, + "week_winning_trades": 8, + "week_total_pnl": 450.75, + "week_win_rate": 66.67 + } + ], + "data_source": "postgresql" +} +``` + +--- + +## Get Day Details + +``` +GET /api/day-details +``` + +Retrieves detailed trades and dividends for a specific day. + +**Query Parameters:** +- `date` (string, required): Date in YYYY-MM-DD format + +**Example:** +```http +GET /api/day-details?date=2024-08-15 +``` + +**Response:** +```json +{ + "success": true, + "date": "2024-08-15", + "trades": [ + { + "symbol": "AAPL", + "buy_date": "2024-08-01", + "sell_date": "2024-08-15", + "buy_price": 195.50, + "sell_price": 198.75, + "volume": 100, + "total_profit_loss": 325.00, + "return_percentage": 1.66, + "trade_result": "Win" + } + ], + "dividends": [ + { + "symbol": "MSFT", + "transaction_date": "2024-08-15", + "action": "Cash Dividend", + "amount": 75.50 + } + ], + "summary": { + "date": "2024-08-15", + "total_trading_pnl": 325.00, + "total_dividends": 75.50, + "total_pnl": 400.50, + "trade_count": 1, + "dividend_count": 1, + "winning_trades": 1, + "win_rate": 100.0 + }, + "data_source": "postgresql" +} +``` + +--- + +## Export Calendar Day Data + +``` +GET /api/calendar/export/ +``` + +Export trades for a specific day in CSV, Excel, or PDF format. + +**Parameters:** +- `format` (path): Export format - `csv`, `excel`, or `pdf` + +**Query Parameters:** +- `date` (string, required): Date in YYYY-MM-DD format + +**Example:** +```http +GET /api/calendar/export/csv?date=2024-08-15 +GET /api/calendar/export/excel?date=2024-08-15 +GET /api/calendar/export/pdf?date=2024-08-15 +``` + +**Response:** File download in requested format + +**Error Response:** +```json +{ + "success": false, + "error": "No trades found for this date" +} +``` +HTTP Status: `404 Not Found` + +--- + +## Get Trading Calendar Metrics + +``` +GET /api/trading-calendar/metrics +``` + +Retrieves trading calendar metrics including market open/close times and trading days. + +**Authentication:** Not required (public endpoint) + +**Response:** +```json +{ + "success": true, + "metrics": { + "current_time": "2024-08-15T14:30:00", + "market_status": "open", + "market_open_time": "09:30:00", + "market_close_time": "16:00:00", + "is_trading_day": true, + "next_trading_day": "2024-08-16", + "trading_days_this_month": 22, + "trading_days_this_year": 252 + } +} +``` + +**Market Status Values:** +- `open` - Market is currently open for trading +- `closed` - Market is closed +- `pre-market` - Before regular trading hours +- `after-hours` - After regular trading hours + +--- + +## Export Monthly Data + +``` +GET /api/monthly/export/ +``` + +Export monthly trading data in CSV, Excel, or PDF format. + +**Parameters:** +- `format` (path): Export format - `csv`, `excel`, or `pdf` + +**Query Parameters:** +- `month` (string, required): Month in YYYY-MM format + +**Example:** +```http +GET /api/monthly/export/pdf?month=2024-08 +GET /api/monthly/export/excel?month=2024-08 +GET /api/monthly/export/csv?month=2024-08 +``` + +**Response:** File download with monthly summary, trades, and dividends + +--- + +## Use Cases + + + + Display monthly trading activity with visual heat maps + + + Drill down into specific trading days + + + Generate reports for tax or record keeping + + + Track market status and trading days + + + +## Related Documentation + + + + Learn about the calendar visualization + + + Get complete monthly trading data + + diff --git a/api-reference/health.mdx b/api-reference/health.mdx new file mode 100644 index 0000000..d1fe5f4 --- /dev/null +++ b/api-reference/health.mdx @@ -0,0 +1,129 @@ +--- +title: 'Health Check Endpoints' +description: 'Health and readiness check endpoints for monitoring' +--- + +## Overview + +Health check endpoints are used for monitoring, load balancers, and Kubernetes orchestration. These endpoints do not require authentication. + +## Basic Health Check + +``` +GET /health +``` + +Basic health check endpoint for load balancers and monitoring systems. + +**Authentication:** Not required + +### Response + +```json +{ + "status": "healthy", + "timestamp": "2025-11-14T10:30:00.000000", + "service": "stocks-trading-analysis" +} +``` + +**HTTP Status:** `200 OK` + +## Detailed Health Check + +``` +GET /health/detailed +``` + +Comprehensive health check including database connectivity, environment variables, and disk space. + +**Authentication:** Not required + +### Response + +```json +{ + "status": "healthy", + "timestamp": "2025-11-14T10:30:00.000000", + "service": "stocks-trading-analysis", + "checks": { + "database": { + "status": "healthy", + "message": "Database connection successful" + }, + "environment": { + "status": "healthy", + "message": "All required environment variables are set" + }, + "disk_space": { + "status": "healthy", + "message": "Disk space OK: 45.23GB free" + } + } +} +``` + +**HTTP Status:** +- `200 OK` - All checks healthy +- `503 Service Unavailable` - One or more checks degraded + +## Readiness Check + +``` +GET /health/ready +``` + +Kubernetes readiness probe to determine if the application is ready to serve traffic. + +**Authentication:** Not required + +### Response + +```json +{ + "status": "ready", + "timestamp": "2025-11-14T10:30:00.000000" +} +``` + +**HTTP Status:** +- `200 OK` - Application ready +- `503 Service Unavailable` - Application not ready + +## Liveness Check + +``` +GET /health/live +``` + +Kubernetes liveness probe to verify the application is running and responsive. + +**Authentication:** Not required + +### Response + +```json +{ + "status": "alive", + "timestamp": "2025-11-14T10:30:00.000000" +} +``` + +**HTTP Status:** `200 OK` + +## Use Cases + + + + Use `/health` endpoint for basic health checks + + + Use `/health/ready` and `/health/live` for orchestration + + + Use `/health/detailed` for comprehensive system monitoring + + + Verify deployment health before routing traffic + + diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 357db6a..61d8e57 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -40,15 +40,27 @@ All API endpoints require authentication via Google OAuth 2.0. The API uses sess Access monthly trading data, P&L reports, and individual trade details + + Get symbol lists, trading statistics, and detailed performance data + + + View daily trading activity, export reports, and market metrics + Manage portfolio holdings and trigger price updates + + Upload CSV files and view import history + Query trading performance across custom date ranges OAuth endpoints and session management + + Monitor application health and readiness + ## Response Format @@ -238,15 +250,27 @@ if (!data.success) { ## Next Steps + + Application monitoring and health endpoints + Learn about OAuth flow and session management Explore trading data endpoints + + Symbol lists and performance data + Manage portfolio holdings + + Daily activity and export reports + + + Upload and track CSV imports + Query custom date ranges diff --git a/api-reference/portfolio-additional.mdx b/api-reference/portfolio-additional.mdx new file mode 100644 index 0000000..9a44408 --- /dev/null +++ b/api-reference/portfolio-additional.mdx @@ -0,0 +1,240 @@ +--- +title: 'Portfolio Additional Operations' +description: 'Additional portfolio endpoints for validation, pricing, snapshots, and CSV upload' +--- + +## Validate Symbol + +``` +GET /api/portfolio/validate-symbol/ +``` + +Validate a stock symbol using Finnhub API before adding to portfolio. + +**Parameters:** +- `symbol` (path): Stock ticker symbol + +**Response:** +```json +{ + "valid": true, + "symbol": "AAPL", + "current_price": 195.50, + "message": "AAPL is a valid symbol" +} +``` + +**Error Response:** +```json +{ + "valid": false, + "symbol": "INVALID", + "error": "Symbol \"INVALID\" not found or invalid" +} +``` + +--- + +## Get Symbol Price + +``` +GET /api/portfolio/price/ +``` + +Get current price for a symbol and update cache. + +**Parameters:** +- `symbol` (path): Stock ticker symbol + +**Response:** +```json +{ + "success": true, + "symbol": "AAPL", + "price_data": { + "current_price": 195.50, + "change": 2.50, + "percent_change": 1.3, + "high": 196.75, + "low": 193.25, + "open": 194.00, + "previous_close": 193.00 + } +} +``` + +--- + +## Capture Portfolio Snapshot + +``` +POST /api/portfolio/snapshot +``` + +Capture a snapshot of current portfolio value for historical tracking. + +**Request Body:** +```json +{ + "snapshot_type": "MANUAL", + "notes": "Monthly review" +} +``` + +**Response:** +```json +{ + "success": true, + "snapshot": { + "id": 1, + "snapshot_time": "2024-08-15T14:30:00", + "total_value": 195500.00, + "total_cost": 150500.00, + "total_gain_loss": 45000.00, + "total_return_pct": 29.9, + "holdings_count": 10 + } +} +``` + +**Snapshot Types:** +- `MANUAL` - User-initiated snapshot +- `AUTOMATIC` - System-generated snapshot +- `EOD` - End of day snapshot + +--- + +## Get Portfolio History + +``` +GET /api/portfolio/history +``` + +Get historical portfolio value snapshots for charting and analysis. + +**Query Parameters:** +- `days` (number, optional): Number of days to retrieve (default: 30, 0 for all) +- `type` (string, optional): Filter by snapshot type + +**Example:** +```http +GET /api/portfolio/history?days=90&type=AUTOMATIC +``` + +**Response:** +```json +{ + "history": [ + { + "id": 1, + "snapshot_time": "2024-08-15T14:30:00", + "total_value": 195500.00, + "total_cost": 150500.00, + "total_gain_loss": 45000.00, + "total_return_pct": 29.9, + "holdings_count": 10, + "snapshot_type": "AUTOMATIC", + "notes": "" + } + ] +} +``` + +--- + +## Delete Portfolio Snapshot + +``` +DELETE /api/portfolio/snapshot/ +``` + +Delete a portfolio snapshot. + +**Parameters:** +- `snapshot_id` (path): ID of the snapshot to delete + +**Response:** +```json +{ + "success": true, + "message": "Deleted MANUAL snapshot from 2024-08-15T14:30:00" +} +``` + +--- + +## Upload Portfolio CSV + +``` +POST /api/portfolio/upload-csv +``` + +or + +``` +POST /api/portfolio/upload +``` + +Upload CSV file with portfolio holdings for bulk import. + +**Content-Type:** `multipart/form-data` + +**Parameters:** +- `csv_file` (file, required): CSV file with holdings + +**CSV Format:** + +Required columns: `symbol`, `shares` + +Optional columns: `cost_basis`, `average_cost`, `security_type`, `holding_type`, `type`, `purchase_date`, `notes` + +**Example CSV:** +```csv +symbol,shares,cost_basis,security_type,notes +AAPL,100,150.50,STOCK,Long-term hold +TSLA,50,245.00,STOCK,Growth position +MSFT,75,320.00,STOCK,Tech diversification +``` + +**Response:** +```json +{ + "success": true, + "imported": 15, + "updated": 3, + "errors": [ + "Row 5: Invalid shares value for TSLA" + ], + "message": "Successfully imported 15 holdings and updated 3 existing holdings" +} +``` + +--- + +## Use Cases + + + + Verify symbols before adding to portfolio to prevent errors + + + Get real-time price data for individual symbols + + + Capture snapshots to track portfolio performance over time + + + Import multiple holdings at once from CSV + + + +## Related Documentation + + + + Main portfolio CRUD operations + + + Refresh all portfolio prices + + diff --git a/api-reference/symbol-details.mdx b/api-reference/symbol-details.mdx new file mode 100644 index 0000000..54d232d --- /dev/null +++ b/api-reference/symbol-details.mdx @@ -0,0 +1,186 @@ +--- +title: 'Get Symbol Details' +api: 'GET /api/symbols/' +description: 'Retrieves detailed information for a specific symbol including all trades, dividends, and statistics' +--- + +## Endpoint + +``` +GET /api/symbols/ +``` + +## Authentication + +Requires OAuth 2.0 authentication via session cookies. + +## Parameters + + + Stock ticker symbol (e.g., AAPL, TSLA) + + +## Response + + + Indicates if the request was successful + + + + Detailed symbol data + + + + Stock ticker symbol + + + + Comprehensive trading statistics (see below) + + + + Array of all completed trades for this symbol + + + + Array of all dividend payments for this symbol + + + + + + Database source (always "postgresql") + + +## Example + + +```bash cURL +curl -X GET https://performance.miningwood.com/api/symbols/AAPL \ + -H "Cookie: session=your_session_cookie" +``` + +```javascript JavaScript +async function getSymbolDetails(symbol) { + const response = await fetch(`/api/symbols/${symbol}`); + const data = await response.json(); + + if (data.success) { + const { summary, trades, dividends } = data.data; + console.log(`${symbol} Summary:`, summary); + console.log(`Total Trades: ${trades.length}`); + console.log(`Total Dividends: ${dividends.length}`); + } +} + +getSymbolDetails('AAPL'); +``` + +```python Python +import requests + +def get_symbol_details(symbol): + response = requests.get(f'https://performance.miningwood.com/api/symbols/{symbol}') + data = response.json() + + if data['success']: + return data['data'] + else: + raise Exception(f"Error: {data.get('error')}") + +details = get_symbol_details('AAPL') +print(f"Trading P&L: ${details['summary']['trading_profit_loss']:.2f}") +``` + + +## Response Example + +```json +{ + "success": true, + "data": { + "symbol": "AAPL", + "summary": { + "total_trades": 25, + "trading_profit_loss": 3450.50, + "winning_trades": 18, + "win_rate_percentage": 72.0, + "avg_profit_loss": 138.02, + "min_profit_loss": -250.00, + "max_profit_loss": 550.00, + "avg_return_pct": 2.15, + "min_return_pct": -3.5, + "max_return_pct": 5.8, + "avg_holding_days": 12, + "total_volume": 2500, + "total_cost_basis": 487500.00, + "first_trade_date": "2024-01-15", + "last_trade_date": "2024-08-30", + "total_dividend_payments": 8, + "total_dividends": 320.00, + "avg_dividend_amount": 40.00, + "first_dividend_date": "2024-02-15", + "last_dividend_date": "2024-08-15", + "total_return": 3770.50, + "current_shares_held": 100 + }, + "trades": [ + { + "buy_date": "2024-08-01", + "sell_date": "2024-08-15", + "buy_price": 195.50, + "sell_price": 198.75, + "volume": 100, + "total_profit_loss": 325.00, + "return_percentage": 1.66, + "trade_result": "Win", + "holding_days": 14 + } + ], + "dividends": [ + { + "transaction_date": "2024-08-15", + "action": "Cash Dividend", + "amount": 40.00 + } + ] + }, + "data_source": "postgresql" +} +``` + +## Summary Statistics + +The `summary` object includes: + +| Statistic | Description | +|-----------|-------------| +| **Trading Metrics** | Total trades, winning trades, win rate, average P&L | +| **Performance Range** | Min/max profit loss and return percentages | +| **Holding Pattern** | Average holding days | +| **Volume & Cost** | Total volume traded and cost basis | +| **Dividend Income** | Payment count, total amount, average | +| **Date Range** | First and last trade/dividend dates | +| **Current Position** | Shares currently held | + +## Error Response + +```json +{ + "success": false, + "error": "Symbol not found" +} +``` + +HTTP Status: `404 Not Found` + +## Related Endpoints + + + + Get summary stats for all symbols + + + Filter by date range and symbols + + diff --git a/api-reference/symbols-summary.mdx b/api-reference/symbols-summary.mdx new file mode 100644 index 0000000..a306190 --- /dev/null +++ b/api-reference/symbols-summary.mdx @@ -0,0 +1,182 @@ +--- +title: 'Get Symbols Summary' +api: 'GET /api/symbols/summary' +description: 'Retrieves comprehensive summary data for all traded symbols including trading stats, dividends, and open positions' +--- + +## Endpoint + +``` +GET /api/symbols/summary +``` + +## Authentication + +Requires OAuth 2.0 authentication via session cookies. + +## Parameters + +None + +## Response + + + Indicates if the request was successful + + + + List of symbol summary objects with comprehensive trading statistics + + + + Stock ticker symbol + + + + Total number of completed trades + + + + Total P&L from trades + + + + Number of profitable trades + + + + Win rate percentage + + + + Average profit/loss per trade + + + + Average return percentage + + + + Total shares traded + + + + Number of dividend payments received + + + + Total dividend income + + + + Combined trading P&L and dividends + + + + Date of first trade (YYYY-MM-DD) + + + + Date of most recent trade (YYYY-MM-DD) + + + + Date of first dividend + + + + Date of most recent dividend + + + + Number of shares currently held + + + + Whether user has an open position + + + + + + Database source (always "postgresql") + + +## Example + + +```bash cURL +curl -X GET https://performance.miningwood.com/api/symbols/summary \ + -H "Cookie: session=your_session_cookie" +``` + +```javascript JavaScript +const response = await fetch('/api/symbols/summary'); +const data = await response.json(); + +if (data.success) { + data.symbols.forEach(symbol => { + console.log(`${symbol.symbol}: ${symbol.total_trades} trades, ${symbol.win_rate_percentage}% win rate`); + }); +} +``` + +```python Python +import requests + +response = requests.get('https://performance.miningwood.com/api/symbols/summary') +data = response.json() + +if data['success']: + for symbol in data['symbols']: + print(f"{symbol['symbol']}: ${symbol['trading_profit_loss']:.2f} P&L") +``` + + +## Response Example + +```json +{ + "success": true, + "symbols": [ + { + "symbol": "AAPL", + "total_trades": 25, + "trading_profit_loss": 3450.50, + "winning_trades": 18, + "win_rate_percentage": 72.0, + "avg_profit_loss": 138.02, + "avg_return_percentage": 2.15, + "total_volume": 2500, + "total_dividend_payments": 8, + "total_dividends": 320.00, + "total_return": 3770.50, + "first_trade_date": "2024-01-15", + "last_trade_date": "2024-08-30", + "first_dividend_date": "2024-02-15", + "last_dividend_date": "2024-08-15", + "current_shares_held": 100, + "has_open_position": true + } + ], + "data_source": "postgresql" +} +``` + +## Use Cases + +- Performance comparison across different stocks +- Identifying best and worst performing symbols +- Portfolio allocation decisions based on historical performance +- Risk analysis across different holdings + +## Related Endpoints + + + + Get detailed trade-by-trade information for a specific symbol + + + Get list of all traded symbols + + diff --git a/api-reference/symbols.mdx b/api-reference/symbols.mdx new file mode 100644 index 0000000..574ec2f --- /dev/null +++ b/api-reference/symbols.mdx @@ -0,0 +1,112 @@ +--- +title: 'Get Symbols' +api: 'GET /api/symbols' +description: 'Retrieves a list of all distinct stock symbols that have been traded' +--- + +## Endpoint + +``` +GET /api/symbols +``` + +## Authentication + +Requires OAuth 2.0 authentication via session cookies. + +## Parameters + +None + +## Response + + + Indicates if the request was successful + + + + List of symbol objects + + + + Stock ticker symbol + + + + Company name or cleaned description + + + + + + Database source (always "postgresql") + + +## Example + + +```bash cURL +curl -X GET https://performance.miningwood.com/api/symbols \ + -H "Cookie: session=your_session_cookie" +``` + +```javascript JavaScript +const response = await fetch('/api/symbols'); +const data = await response.json(); + +if (data.success) { + data.symbols.forEach(item => { + console.log(`${item.symbol}: ${item.company_name}`); + }); +} +``` + +```python Python +import requests + +response = requests.get('https://performance.miningwood.com/api/symbols') +data = response.json() + +if data['success']: + for symbol in data['symbols']: + print(f"{symbol['symbol']}: {symbol['company_name']}") +``` + + +## Response Example + +```json +{ + "success": true, + "symbols": [ + { + "symbol": "AAPL", + "company_name": "Apple Inc." + }, + { + "symbol": "TSLA", + "company_name": "Tesla, Inc." + }, + { + "symbol": "MSFT", + "company_name": "Microsoft Corporation" + }, + { + "symbol": "NVDA", + "company_name": "NVIDIA Corporation" + } + ], + "data_source": "postgresql" +} +``` + +## Related Endpoints + + + + Get comprehensive trading statistics for all symbols + + + Get detailed information for a specific symbol + + diff --git a/api-reference/upload-csv.mdx b/api-reference/upload-csv.mdx new file mode 100644 index 0000000..34c654f --- /dev/null +++ b/api-reference/upload-csv.mdx @@ -0,0 +1,195 @@ +--- +title: 'Upload CSV Files' +api: 'POST /api/upload-csv' +description: 'Upload and process transaction history and realized gains CSV files from brokerage' +--- + +## Endpoint + +``` +POST /api/upload-csv +``` + +## Authentication + +Requires OAuth 2.0 authentication and user must have brokerage account number set in profile. + +## Content Type + +`multipart/form-data` + +## Parameters + + + Transaction history CSV file from your brokerage + + + + Realized gains/losses CSV file from your brokerage + + +## Response Format + +The endpoint returns streaming JSON responses to provide real-time progress updates: + +```json +{"type": "progress", "percentage": 25, "message": "Starting data processing..."} +{"type": "progress", "percentage": 40, "message": "Processing transaction history and realized gains..."} +{"type": "progress", "percentage": 60, "message": "Synchronizing with database..."} +{"type": "progress", "percentage": 80, "message": "Finalizing data import..."} +{"type": "success", "message": "Successfully processed files", "stats": {"transactions_inserted": 279, "realized_gains_lots": 713, "broker_verified_trades": 156}} +``` + +## Success Response Fields + + + Response type: "progress", "success", or "error" + + + + Progress percentage (0-100) for progress type responses + + + + Human-readable status message + + + + Import statistics (only in success response) + + + + Number of transactions inserted + + + + Number of realized gain/loss lots processed + + + + Number of broker-verified completed trades + + + + +## Example + + +```javascript JavaScript with Progress +const formData = new FormData(); +formData.append('transaction_history_file', transactionFile); +formData.append('realized_gains_file', gainsFile); + +const response = await fetch('/api/upload-csv', { + method: 'POST', + body: formData +}); + +// Handle streaming response +const reader = response.body.getReader(); +const decoder = new TextDecoder(); + +while (true) { + const { done, value } = await reader.read(); + if (done) break; + + const text = decoder.decode(value); + const lines = text.split('\n').filter(l => l.trim()); + + for (const line of lines) { + const data = JSON.parse(line); + + if (data.type === 'progress') { + console.log(`Progress: ${data.percentage}% - ${data.message}`); + } else if (data.type === 'success') { + console.log('Upload complete!', data.stats); + } else if (data.type === 'error') { + console.error('Upload failed:', data.message); + } + } +} +``` + +```python Python +import requests + +files = { + 'transaction_history_file': open('transactions.csv', 'rb'), + 'realized_gains_file': open('gains.csv', 'rb') +} + +response = requests.post( + 'https://performance.miningwood.com/api/upload-csv', + files=files, + stream=True +) + +for line in response.iter_lines(): + if line: + data = json.loads(line) + if data['type'] == 'progress': + print(f"Progress: {data['percentage']}%") + elif data['type'] == 'success': + print("Upload successful!", data['stats']) +``` + +```bash cURL +curl -X POST https://performance.miningwood.com/api/upload-csv \ + -H "Cookie: session=your_session_cookie" \ + -F "transaction_history_file=@transactions.csv" \ + -F "realized_gains_file=@realized_gains.csv" +``` + + +## Error Responses + +```json +{"type": "error", "message": "Both files must be CSV files"} +``` +HTTP Status: `400 Bad Request` + +```json +{"type": "error", "message": "Brokerage account number not set. Please update your profile."} +``` +HTTP Status: `400 Bad Request` + +```json +{"type": "error", "message": "Both transaction history and realized gains files are required"} +``` +HTTP Status: `400 Bad Request` + +## CSV File Requirements + +### Transaction History File +Should include columns such as: +- Transaction date +- Symbol +- Action (Buy, Sell, etc.) +- Quantity/Shares +- Price +- Amount +- Account number + +### Realized Gains File +Should include columns such as: +- Symbol +- Date acquired +- Date sold +- Proceeds +- Cost basis +- Gain/Loss + + + File format requirements may vary by brokerage. The system attempts to automatically detect and parse common formats. + + +## Related Endpoints + + + + View history of previous uploads + + + Learn more about CSV upload functionality + + diff --git a/api-reference/upload-history.mdx b/api-reference/upload-history.mdx new file mode 100644 index 0000000..19a5cb4 --- /dev/null +++ b/api-reference/upload-history.mdx @@ -0,0 +1,148 @@ +--- +title: 'Get Upload History' +api: 'GET /api/upload-history' +description: 'Retrieves history of CSV file uploads with processing statistics' +--- + +## Endpoint + +``` +GET /api/upload-history +``` + +## Authentication + +Requires OAuth 2.0 authentication via session cookies. + +## Parameters + +None + +## Response + + + Indicates if the request was successful + + + + List of upload history objects + + + + Name of transaction history CSV file + + + + Name of realized gains CSV file + + + + Upload timestamp (ISO 8601 format) + + + + Size of transaction file in bytes + + + + Size of gains file in bytes + + + + Upload status (e.g., "success", "failed") + + + + Email of user who uploaded + + + + Account ID + + + + Brokerage account number + + + + Number of transactions processed + + + + Number of months updated + + + + +## Example + + +```bash cURL +curl -X GET https://performance.miningwood.com/api/upload-history \ + -H "Cookie: session=your_session_cookie" +``` + +```javascript JavaScript +const response = await fetch('/api/upload-history'); +const data = await response.json(); + +if (data.success) { + data.history.forEach(upload => { + console.log(`${upload.timestamp}: ${upload.transactions_processed} transactions`); + }); +} +``` + +```python Python +import requests + +response = requests.get('https://performance.miningwood.com/api/upload-history') +data = response.json() + +if data['success']: + for upload in data['history']: + print(f"{upload['timestamp']}: {upload['status']}") +``` + + +## Response Example + +```json +{ + "success": true, + "history": [ + { + "transaction_filename": "transactions.csv", + "gains_filename": "realized_gains.csv", + "timestamp": "2024-08-15T14:30:00", + "transaction_file_size": 524288, + "gains_file_size": 262144, + "status": "success", + "user_email": "user@example.com", + "account_id": 1, + "brokerage_account": "12345678", + "transactions_processed": 279, + "months_updated": 3 + } + ] +} +``` + +## Use Cases + +- Track upload activity and processing history +- Audit data imports +- Verify successful uploads +- Monitor file sizes and processing metrics +- Troubleshoot import issues + +## Related Endpoints + + + + Upload new transaction and gains files + + + Learn about CSV upload process + + diff --git a/docs.json b/docs.json index 0fd5b4f..99e00d0 100644 --- a/docs.json +++ b/docs.json @@ -44,7 +44,8 @@ { "group": "Overview", "pages": [ - "api-reference/introduction" + "api-reference/introduction", + "api-reference/health" ] }, { @@ -56,11 +57,33 @@ "api-reference/timeframe" ] }, + { + "group": "Symbols", + "pages": [ + "api-reference/symbols", + "api-reference/symbols-summary", + "api-reference/symbol-details" + ] + }, + { + "group": "Calendar", + "pages": [ + "api-reference/calendar" + ] + }, { "group": "Portfolio", "pages": [ "api-reference/portfolio-holdings", - "api-reference/portfolio-refresh" + "api-reference/portfolio-refresh", + "api-reference/portfolio-additional" + ] + }, + { + "group": "Data Import", + "pages": [ + "api-reference/upload-csv", + "api-reference/upload-history" ] }, {