> ## Documentation Index
> Fetch the complete documentation index at: https://docs.miningwood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> RESTful API for the Trading Analysis Dashboard

## Overview

The Trading Analysis Dashboard exposes a RESTful API for accessing trading data, portfolio holdings, and performance metrics programmatically. The API powers the web interface and can be used to build custom integrations or automation tools.

<Card title="Live Application" icon="globe" href="https://performance.miningwood.com">
  Visit the Trading Analysis Dashboard at performance.miningwood.com
</Card>

## Base URL

```
https://performance.miningwood.com
```

For local development:

```
http://localhost:5000
```

## Authentication

All API endpoints require authentication via Google OAuth 2.0. The API uses session-based authentication with HTTP-only cookies set after successful OAuth login.

<Info>
  See the [Authentication guide](/api-reference/auth) for details on the OAuth flow and session management.
</Info>

## API Categories

<CardGroup cols={2}>
  <Card title="Trading Data" icon="chart-line" href="/api-reference/months">
    Access monthly trading data, P\&L reports, and individual trade details
  </Card>

  <Card title="Symbols" icon="tag" href="/api-reference/symbols">
    Get symbol lists, trading statistics, and detailed performance data
  </Card>

  <Card title="Calendar" icon="calendar-days" href="/api-reference/calendar">
    View daily trading activity, export reports, and market metrics
  </Card>

  <Card title="Portfolio" icon="briefcase" href="/api-reference/portfolio-holdings">
    Manage portfolio holdings and trigger price updates
  </Card>

  <Card title="Data Import" icon="upload" href="/api-reference/upload-csv">
    Upload CSV files and view import history
  </Card>

  <Card title="Timeframe Analysis" icon="calendar" href="/api-reference/timeframe">
    Query trading performance across custom date ranges
  </Card>

  <Card title="Authentication" icon="lock" href="/api-reference/auth">
    OAuth endpoints and session management
  </Card>

  <Card title="Health Checks" icon="heart-pulse" href="/api-reference/health">
    Monitor application health and readiness
  </Card>
</CardGroup>

## Response Format

All API responses return JSON with a consistent structure:

### Success Response

```json theme={null}
{
  "success": true,
  "data": { ... },
  "data_source": "postgresql"
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": "Error message description"
}
```

## Common Response Fields

| Field               | Type    | Description                                              |
| ------------------- | ------- | -------------------------------------------------------- |
| `success`           | boolean | Indicates if the request was successful                  |
| `error`             | string  | Error message (only present on failure)                  |
| `data_source`       | string  | Database source (typically "postgresql")                 |
| `redirect_to_login` | boolean | Whether client should redirect to login (for 401 errors) |

## HTTP Status Codes

The API uses standard HTTP status codes:

| Code  | Meaning               | When Used                  |
| ----- | --------------------- | -------------------------- |
| `200` | OK                    | Successful request         |
| `400` | Bad Request           | Invalid request parameters |
| `401` | Unauthorized          | Authentication required    |
| `403` | Forbidden             | User not authorized        |
| `404` | Not Found             | Resource not found         |
| `500` | Internal Server Error | Server-side error          |

## Rate Limiting

<Note>
  The API does not currently implement rate limiting, but the Finnhub price refresh endpoint is subject to Finnhub's API rate limits (60 requests/minute for free tier).
</Note>

## Data Types

### Date Formats

* **Months**: `YYYY-MM` format (e.g., `"2024-08"`)
* **Dates**: `YYYY-MM-DD` format (e.g., `"2024-08-15"`)
* **Timestamps**: ISO 8601 format (e.g., `"2024-08-15T14:30:00Z"`)

### Numeric Values

* **Prices**: Decimal with 2-4 decimal places
* **Shares**: Integer or decimal (supports fractional shares)
* **P\&L Values**: Decimal with 2 decimal places (can be negative)
* **Percentages**: Decimal (e.g., `0.1523` for 15.23%)

## Example Usage

### Fetch Available Trading Months

```bash theme={null}
curl -X GET https://performance.miningwood.com/api/months \
  -H "Cookie: session=your_session_cookie"
```

### Get Portfolio Holdings

```bash theme={null}
curl -X GET https://performance.miningwood.com/api/portfolio/holdings \
  -H "Cookie: session=your_session_cookie"
```

### Analyze Custom Timeframe

```bash theme={null}
curl -X GET "https://performance.miningwood.com/api/timeframe?start_date=2024-01-01&end_date=2024-06-30" \
  -H "Cookie: session=your_session_cookie"
```

## Client Libraries

The API can be accessed using any HTTP client library:

<CodeGroup>
  ```javascript JavaScript (Fetch) theme={null}
  const response = await fetch('/api/months', {
    credentials: 'include' // Include cookies
  });
  const data = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  session = requests.Session()
  response = session.get('https://performance.miningwood.com/api/months')
  data = response.json()
  ```

  ```bash cURL theme={null}
  curl -X GET https://performance.miningwood.com/api/months \
    --cookie-jar cookies.txt \
    --cookie cookies.txt
  ```
</CodeGroup>

## Data Models

### Trade Object

```json theme={null}
{
  "symbol": "AAPL",
  "buy_date": "2024-01-15",
  "sell_date": "2024-03-20",
  "buy_price": 150.25,
  "sell_price": 165.80,
  "volume": 100,
  "profit_loss": 1555.00,
  "return_percentage": 10.35
}
```

### Holding Object

```json theme={null}
{
  "id": 123,
  "symbol": "MSFT",
  "type": "stock",
  "shares": 50,
  "average_cost": 320.50,
  "current_price": 345.20,
  "market_value": 17260.00,
  "gain_loss": 1235.00,
  "gain_loss_percentage": 7.70,
  "last_updated": "2024-08-15T14:30:00Z"
}
```

### Month Summary Object

```json theme={null}
{
  "month": "2024-08",
  "total_trades": 15,
  "winning_trades": 10,
  "win_rate": 66.67,
  "trading_pl": 1250.75,
  "dividend_income": 125.50,
  "total_return_with_dividends": 1376.25
}
```

## Error Handling

Always check the `success` field before processing response data:

```javascript theme={null}
const response = await fetch('/api/months');
const data = await response.json();

if (!data.success) {
  console.error('API Error:', data.error);
  
  if (data.redirect_to_login) {
    window.location.href = '/auth/login';
  }
  return;
}

// Process data.months
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Health Checks" icon="heart-pulse" href="/api-reference/health">
    Application monitoring and health endpoints
  </Card>

  <Card title="Authentication" icon="lock" href="/api-reference/auth">
    Learn about OAuth flow and session management
  </Card>

  <Card title="Trading Data" icon="chart-line" href="/api-reference/months">
    Explore trading data endpoints
  </Card>

  <Card title="Symbols" icon="tag" href="/api-reference/symbols">
    Symbol lists and performance data
  </Card>

  <Card title="Portfolio API" icon="briefcase" href="/api-reference/portfolio-holdings">
    Manage portfolio holdings
  </Card>

  <Card title="Calendar" icon="calendar-days" href="/api-reference/calendar">
    Daily activity and export reports
  </Card>

  <Card title="Data Import" icon="upload" href="/api-reference/upload-csv">
    Upload and track CSV imports
  </Card>

  <Card title="Timeframe Analysis" icon="calendar" href="/api-reference/timeframe">
    Query custom date ranges
  </Card>
</CardGroup>