Research API

Path Parameters

• ticker string required
  Stock ticker symbol (e.g., "AAPL.US")
• snapshot_id string required
  Snapshot ID (format: YYYYMMDD_HHMMSS)

Request Body

{
  "query": "Provide a comprehensive analysis of Apple Inc.",
  "template": "deep_dive"
}

Request Parameters

Example Request - Template (cURL)

curl -X POST \
  "http://localhost:8004/api/stocks/AAPL.US/snapshots/20251016_143022/research/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Provide a comprehensive analysis of Apple Inc.",
    "template": "deep_dive"
  }'

Example Request - Custom Query (Python)

import requests

response = requests.post(
    "http://localhost:8004/api/stocks/AAPL.US/snapshots/20251016_143022/research/generate",
    json={
        "query": "What are Apple's competitive advantages in the smartphone market?",
        "template": null  # Custom query, no template
    }
)

research = response.json()
print(f"Report saved to: {research['saved_path']}")
print(f"Sources: {len(research['sources'])}")
print(research['report'][:500])  # Print first 500 chars

Processing Flow

This endpoint performs the following research steps:

1. Validates API keys (OpenAI and Tavily) from Settings
2. Initializes GPT-Researcher with ticker and API keys
3. If template specified: Uses predefined research query and methodology
4. If custom query: Researches the exact question provided
5. Searches the web using Tavily API (10-20 sources)
6. Synthesizes findings using GPT-4
7. Generates structured Markdown report with sources
8. Saves report to /stocks/{ticker}/{snapshot_id}/research/
9. Returns report content and metadata

Typical execution time: 60-120 seconds

Response (200 OK)

{
  "query": "Provide a comprehensive analysis of Apple Inc.",
  "report": "# Apple Inc. - Comprehensive Analysis\n\n## Executive Summary\n\nApple Inc. (NASDAQ: AAPL) is the world's largest technology company...\n\n## Company Overview\n\nFounded in 1976, Apple has evolved from a personal computer manufacturer...\n\n## Products and Services\n\n### iPhone\nThe iPhone represents approximately 52% of total revenue...\n\n### Services\nApple's services segment has grown to $85B annually...\n\n## Competitive Position\n\nApple maintains strong competitive moats through...\n\n## Financial Performance\n\nRevenue: $394B (FY2023)\nGross Margin: 44%\nNet Income: $97B\n\n## Outlook\n\nKey growth drivers include...\n\n## Conclusion\n\nApple demonstrates exceptional fundamentals...",
  "sources": [
    "https://www.apple.com/investor/",
    "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193",
    "https://www.bloomberg.com/quote/AAPL:US",
    "https://www.cnbc.com/apple/",
    "https://9to5mac.com/guides/iphone/",
    "https://www.macrumors.com/",
    "https://www.statista.com/statistics/apple/",
    "https://www.marketwatch.com/investing/stock/aapl"
  ],
  "report_type": "deep_dive",
  "ticker": "AAPL.US",
  "saved_path": "/home/user/stocks/AAPL.US/20251016_143022/research/research_deep_dive_20251016_153045.md"
}

Response Fields

Error Responses

Path Parameters

• ticker string required
  Stock ticker symbol
• snapshot_id string required
  Snapshot ID (format: YYYYMMDD_HHMMSS)

Example Request

curl "http://localhost:8004/api/stocks/AAPL.US/snapshots/20251016_143022/research/files"

Response (200 OK)

[
  {
    "filename": "research_deep_dive_20251016_153045.md",
    "path": "/home/user/stocks/AAPL.US/20251016_143022/research/research_deep_dive_20251016_153045.md",
    "size_kb": 52.3,
    "modified": 1729089045.234
  },
  {
    "filename": "research_risk_20251016_145022.md",
    "path": "/home/user/stocks/AAPL.US/20251016_143022/research/research_risk_20251016_145022.md",
    "size_kb": 38.7,
    "modified": 1729087822.156
  },
  {
    "filename": "research_custom_20251016_140512.md",
    "path": "/home/user/stocks/AAPL.US/20251016_143022/research/research_custom_20251016_140512.md",
    "size_kb": 28.1,
    "modified": 1729086312.789
  }
]

Response Fields

Note: Results are sorted by modified date (newest first).

Path Parameters

• ticker string required
  Stock ticker symbol
• snapshot_id string required
  Snapshot ID
• filename string required
  Research report filename (must start with "research_" and end with ".md")

Example Request

curl "http://localhost:8004/api/stocks/AAPL.US/snapshots/20251016_143022/research/content/research_deep_dive_20251016_153045.md"

Response (200 OK)

{
  "filename": "research_deep_dive_20251016_153045.md",
  "content": "# Research Report: Provide a comprehensive analysis of Apple Inc.\n\n**Ticker:** AAPL.US\n\n**Report Type:** deep_dive\n\n---\n\n# Apple Inc. - Comprehensive Analysis\n\n## Executive Summary\n\nApple Inc. (NASDAQ: AAPL) is the world's largest technology company...\n\n[Full markdown content here]\n\n---\n\n## Sources\n\n1. https://www.apple.com/investor/\n2. https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193\n3. https://www.bloomberg.com/quote/AAPL:US\n..."
}

Security Validation

This endpoint validates filenames to prevent directory traversal attacks:

• Must start with research_
• Must end with .md
• Cannot contain / or ..

Error Responses

Path Parameters

• ticker string required
  Stock ticker symbol
• snapshot_id string required
  Snapshot ID
• filename string required
  Research report filename to delete

Example Request

curl -X DELETE \
  "http://localhost:8004/api/stocks/AAPL.US/snapshots/20251016_143022/research/research_custom_20251016_140512.md"

Response (200 OK)

{
  "message": "Research file deleted successfully",
  "filename": "research_custom_20251016_140512.md"
}

Error Responses