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

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:

{
  "company_name": "NVIDIA"
}

Response:

{
  "cik": "0001045810",
  "name": "NVIDIA CORP",
  "ticker": "NVDA",
  "error": null
}

cURL Example:

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

Python Example:

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:

{
  "cik": "0001045810"
}

Response:

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

cURL Example:

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

Python Example:

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):

{
  "cik": "0001045810",
  "form_types": null
}

Request (Specific form types):

{
  "cik": "0001045810",
  "form_types": ["10-K", "10-Q"]
}

Response:

{
  "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:

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:

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:

{
  "cik": "0001045810"
}

Response:

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

cURL Example:

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

Python Example:

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):

{
  "cik": "0001045810",
  "period": "2024"
}

Request (Quarterly Data):

{
  "cik": "0001045810",
  "period": "2024Q3"
}

Response:

{
  "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:

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:

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

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

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:

{
  "detail": "Error message description"
}

Or for API-specific errors:

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