API_USAGE.md

# API Usage Guide

Complete guide for using the SEC Financial Report MCP Server API.

## Base URL

After deployment: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`

## Interactive Documentation

- **Swagger UI**: `{BASE_URL}/docs`
- **ReDoc**: `{BASE_URL}/redoc`

## Quick Start

### Python Example

```python
import requests

BASE_URL = "https://YOUR_SPACE_URL.hf.space"

# 1. Search company
response = requests.post(
    f"{BASE_URL}/api/search_company",
    json={"company_name": "NVIDIA"}
)
company = response.json()
print(f"Found: {company['name']} (CIK: {company['cik']})")

# 2. Get financial data
response = requests.post(
    f"{BASE_URL}/api/get_financial_data",
    json={"cik": company['cik'], "period": "2024"}
)
data = response.json()
print(f"Revenue: ${data['total_revenue']:,.0f}")
print(f"Net Income: ${data['net_income']:,.0f}")
print(f"EPS: ${data['earnings_per_share']:.2f}")
```

## Base URL

```
https://your-space-name.hf.space
```

## API Endpoints

### 1. Search Company by Name

**Endpoint:** `POST /api/search_company`

**Request:**
```json
{
  "company_name": "NVIDIA"
}
```

**Response:**
```json
{
  "cik": "0001045810",
  "name": "NVIDIA CORP",
  "ticker": "NVDA",
  "error": null
}
```

**cURL Example:**
```bash
curl -X POST "https://your-space-name.hf.space/api/search_company" \
  -H "Content-Type: application/json" \
  -d '{"company_name": "NVIDIA"}'
```

**Python Example:**
```python
import requests

url = "https://your-space-name.hf.space/api/search_company"
payload = {"company_name": "NVIDIA"}
response = requests.post(url, json=payload)
print(response.json())
```

---

### 2. Get Company Information

**Endpoint:** `POST /api/get_company_info`

**Request:**
```json
{
  "cik": "0001045810"
}
```

**Response:**
```json
{
  "cik": "0001045810",
  "name": "NVIDIA CORP",
  "tickers": ["NVDA"],
  "sic": "3674",
  "sic_description": "Semiconductors & Related Devices",
  "error": null
}
```

**cURL Example:**
```bash
curl -X POST "https://your-space-name.hf.space/api/get_company_info" \
  -H "Content-Type: application/json" \
  -d '{"cik": "0001045810"}'
```

**Python Example:**
```python
import requests

url = "https://your-space-name.hf.space/api/get_company_info"
payload = {"cik": "0001045810"}
response = requests.post(url, json=payload)
print(response.json())
```

---

### 3. Get Company Filings

**Endpoint:** `POST /api/get_company_filings`

**Request (All form types):**
```json
{
  "cik": "0001045810",
  "form_types": null
}
```

**Request (Specific form types):**
```json
{
  "cik": "0001045810",
  "form_types": ["10-K", "10-Q"]
}
```

**Response:**
```json
{
  "filings": [
    {
      "form_type": "10-K",
      "filing_date": "2024-02-21",
      "accession_number": "0001045810-24-000029",
      "primary_document": "nvda-20240128.htm"
    },
    {
      "form_type": "10-Q",
      "filing_date": "2024-05-22",
      "accession_number": "0001045810-24-000067",
      "primary_document": "nvda-20240428.htm"
    }
  ],
  "error": null
}
```

**cURL Example:**
```bash
curl -X POST "https://your-space-name.hf.space/api/get_company_filings" \
  -H "Content-Type: application/json" \
  -d '{"cik": "0001045810", "form_types": ["10-K", "10-Q"]}'
```

**Python Example:**
```python
import requests

url = "https://your-space-name.hf.space/api/get_company_filings"
payload = {
    "cik": "0001045810",
    "form_types": ["10-K", "10-Q"]
}
response = requests.post(url, json=payload)
print(response.json())
```

---

### 4. Get Company Facts

**Endpoint:** `POST /api/get_company_facts`

**Request:**
```json
{
  "cik": "0001045810"
}
```

**Response:**
```json
{
  "facts": {
    "dei": {
      "EntityCommonStockSharesOutstanding": {...},
      "EntityPublicFloat": {...}
    },
    "us-gaap": {
      "Revenues": {...},
      "NetIncomeLoss": {...},
      "EarningsPerShareBasic": {...}
    }
  },
  "error": null
}
```

**cURL Example:**
```bash
curl -X POST "https://your-space-name.hf.space/api/get_company_facts" \
  -H "Content-Type: application/json" \
  -d '{"cik": "0001045810"}'
```

**Python Example:**
```python
import requests

url = "https://your-space-name.hf.space/api/get_company_facts"
payload = {"cik": "0001045810"}
response = requests.post(url, json=payload)
print(response.json())
```

---

### 5. Get Financial Data for Period

**Endpoint:** `POST /api/get_financial_data`

**Request (Annual Data):**
```json
{
  "cik": "0001045810",
  "period": "2024"
}
```

**Request (Quarterly Data):**
```json
{
  "cik": "0001045810",
  "period": "2024Q3"
}
```

**Response:**
```json
{
  "period": "2024",
  "total_revenue": 60922000000,
  "net_income": 29760000000,
  "earnings_per_share": 12.04,
  "operating_expenses": 11822000000,
  "operating_cash_flow": 28091000000,
  "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581024000029",
  "source_form": "10-K",
  "data_source": "us-gaap",
  "additional_details": {
    "total_revenue_details": {
      "tag": "Revenues",
      "form": "10-K",
      "fy": 2024,
      "fp": "FY",
      "val": 60922000000,
      "start": "2023-01-30",
      "end": "2024-01-28",
      "accn": "0001045810-24-000029",
      "filed": "2024-02-21",
      "frame": "CY2023",
      "data_source": "us-gaap"
    }
  },
  "error": null
}
```

**cURL Example:**
```bash
curl -X POST "https://your-space-name.hf.space/api/get_financial_data" \
  -H "Content-Type: application/json" \
  -d '{"cik": "0001045810", "period": "2024"}'
```

**Python Example:**
```python
import requests

url = "https://your-space-name.hf.space/api/get_financial_data"
payload = {
    "cik": "0001045810",
    "period": "2024"
}
response = requests.post(url, json=payload)
data = response.json()
print(f"Total Revenue: ${data['total_revenue']:,.0f}")
print(f"Net Income: ${data['net_income']:,.0f}")
print(f"EPS: ${data['earnings_per_share']:.2f}")
```

---

## Complete Python Client Example

```python
import requests
import json


class SECMCPClient:
    """Client for SEC Financial Report MCP Server"""
    
    def __init__(self, base_url):
        self.base_url = base_url.rstrip('/')
    
    def search_company(self, company_name):
        """Search company by name"""
        url = f"{self.base_url}/api/search_company"
        response = requests.post(url, json={"company_name": company_name})
        return response.json()
    
    def get_company_info(self, cik):
        """Get company information"""
        url = f"{self.base_url}/api/get_company_info"
        response = requests.post(url, json={"cik": cik})
        return response.json()
    
    def get_company_filings(self, cik, form_types=None):
        """Get company filings"""
        url = f"{self.base_url}/api/get_company_filings"
        payload = {"cik": cik, "form_types": form_types}
        response = requests.post(url, json=payload)
        return response.json()
    
    def get_company_facts(self, cik):
        """Get company facts"""
        url = f"{self.base_url}/api/get_company_facts"
        response = requests.post(url, json={"cik": cik})
        return response.json()
    
    def get_financial_data(self, cik, period):
        """Get financial data for period"""
        url = f"{self.base_url}/api/get_financial_data"
        payload = {"cik": cik, "period": period}
        response = requests.post(url, json=payload)
        return response.json()


# Usage example
if __name__ == "__main__":
    # Initialize client
    client = SECMCPClient("https://your-space-name.hf.space")
    
    # Search for a company
    company = client.search_company("NVIDIA")
    print(f"Found: {company['name']} (CIK: {company['cik']})")
    
    # Get company information
    info = client.get_company_info(company['cik'])
    print(f"Industry: {info['sic_description']}")
    
    # Get recent filings
    filings = client.get_company_filings(company['cik'], ["10-K"])
    print(f"Recent 10-K filings: {len(filings['filings'])}")
    
    # Get financial data for 2024
    financial_data = client.get_financial_data(company['cik'], "2024")
    print(f"FY2024 Revenue: ${financial_data['total_revenue']:,.0f}")
    print(f"FY2024 Net Income: ${financial_data['net_income']:,.0f}")
    print(f"FY2024 EPS: ${financial_data['earnings_per_share']:.2f}")
```

---

## Complete JavaScript/Node.js Client Example

```javascript
const axios = require('axios');

class SECMCPClient {
    constructor(baseUrl) {
        this.baseUrl = baseUrl.replace(/\/$/, '');
    }

    async searchCompany(companyName) {
        const response = await axios.post(
            `${this.baseUrl}/api/search_company`,
            { company_name: companyName }
        );
        return response.data;
    }

    async getCompanyInfo(cik) {
        const response = await axios.post(
            `${this.baseUrl}/api/get_company_info`,
            { cik: cik }
        );
        return response.data;
    }

    async getCompanyFilings(cik, formTypes = null) {
        const response = await axios.post(
            `${this.baseUrl}/api/get_company_filings`,
            { cik: cik, form_types: formTypes }
        );
        return response.data;
    }

    async getCompanyFacts(cik) {
        const response = await axios.post(
            `${this.baseUrl}/api/get_company_facts`,
            { cik: cik }
        );
        return response.data;
    }

    async getFinancialData(cik, period) {
        const response = await axios.post(
            `${this.baseUrl}/api/get_financial_data`,
            { cik: cik, period: period }
        );
        return response.data;
    }
}

// Usage example
(async () => {
    const client = new SECMCPClient('https://your-space-name.hf.space');
    
    // Search for a company
    const company = await client.searchCompany('NVIDIA');
    console.log(`Found: ${company.name} (CIK: ${company.cik})`);
    
    // Get financial data
    const financialData = await client.getFinancialData(company.cik, '2024');
    console.log(`FY2024 Revenue: $${financialData.total_revenue.toLocaleString()}`);
    console.log(`FY2024 Net Income: $${financialData.net_income.toLocaleString()}`);
    console.log(`FY2024 EPS: $${financialData.earnings_per_share.toFixed(2)}`);
})();
```

---

## Error Handling

All endpoints return standard HTTP status codes:

- **200 OK**: Successful request
- **422 Unprocessable Entity**: Invalid request parameters
- **500 Internal Server Error**: Server error

Error response format:
```json
{
  "detail": "Error message description"
}
```

Or for API-specific errors:
```json
{
  "error": "No company found matching 'INVALID_NAME'"
}
```

---

## Notes

- All monetary values are in USD (original values, not converted to millions)
- The `earnings_per_share` value is per share
- Data source: US SEC EDGAR system
- Supports US-GAAP and IFRS standards
- User-Agent: Juntao Peng (jtyxabc@gmail.com)
- Rate limiting follows SEC EDGAR API guidelines (10 requests per second)

---

## Interactive API Documentation

Once deployed, you can access interactive API documentation at:

- Swagger UI: `https://your-space-name.hf.space/docs`
- ReDoc: `https://your-space-name.hf.space/redoc`