API Documentation

Automated financial analysis powered by AI research. Analyze stocks and portfolios with multi-round research for informed investment decisions.

Quick Start in 3 Steps

1

Get API Key

Generate your API key in the portal:

Go to API Portal →
2

Start Analysis

curl -X POST https://partner.rize.capital/api/analysis/stock-report/create \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["AAPL"]}'
3

Get Results

curl -X GET https://partner.rize.capital/api/analysis/stock-report/jobs/{job_id}/result \
  -H "Authorization: Bearer YOUR_KEY"

Complete Python Example

import requests
import time

# Configuration
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://partner.rize.capital/api"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. Create analysis
create_response = requests.post(
    f"{BASE_URL}/analysis/stock-report/create",
    headers=headers,
    json={
        "symbols": ["AAPL", "MSFT"],
        "prompt": "Compare AI strategies and competitive positioning",
        "output_format": {"type": "json_schema"}
    }
)
job_id = create_response.json()["job_id"]
print(f"Analysis started: {job_id}")

# 2. Check status
while True:
    status_response = requests.get(
        f"{BASE_URL}/analysis/stock-report/jobs/{job_id}/status",
        headers=headers
    )
    status_data = status_response.json()

    print(f"Status: {status_data['status']} ({status_data.get('progress', 0)}%)")

    if status_data["status"] == "completed":
        break
    elif status_data["status"] == "failed":
        print(f"Error: {status_data.get('error', 'Unknown error')}")
        exit(1)

    time.sleep(5)

# 3. Get result
result_response = requests.get(
    f"{BASE_URL}/analysis/stock-report/jobs/{job_id}/result",
    headers=headers
)
result = result_response.json()

print("\nAnalysis completed!")
print(f"Duration: {result['metadata']['duration_seconds']}s")
print(f"Research rounds: {result['metadata']['rounds_completed']}")
print("\nResult:", result["result"])

Practical Use Cases

Single Stock Analysis

Deep dive into a stock with specific focus areas

{
  "symbols": ["NVDA"],
  "prompt": "Analyze NVIDIA's competitive position in AI chips. What risks could threaten the current valuation?",
  "output_format": {
    "type": "json_schema",
    "json_schema": {
      "competitive_analysis": "object",
      "risk_factors": "array",
      "valuation_assessment": "object",
      "recommendation": "string"
    }
  }
}

Comparative Analysis

Direct comparison of multiple companies

{
  "symbols": ["TSLA", "F", "GM", "RIVN"],
  "prompt": "Compare EV strategies. Who has the best chance for profitable growth in the next 3 years?"
}

Portfolio Assessment

Risk and diversification analysis

{
  "portfolio_composition": [
    {"symbol": "AAPL", "percentage": 35},
    {"symbol": "MSFT", "percentage": 30},
    {"symbol": "GOOGL", "percentage": 20},
    {"symbol": "BRK.B", "percentage": 15}
  ],
  "prompt": "Assess concentration risks and suggest diversification"
}

Thematic Analysis

Industry trends and future themes

{
  "symbols": ["PLTR", "SNOW", "DDOG", "MDB"],
  "prompt": "Analyze growth potential in data analytics sector. Which company is best positioned?"
}

API Reference

Authentication

Important: All API requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Stock Analysis Endpoints

POST /api/analysis/stock-report/create

Creates a new stock analysis with AI-powered research

Request Body:

{
  "symbols": ["AAPL", "MSFT"],        // Required: 1-10 stock symbols
  "prompt": "Analysis focus",         // Optional: Specific question
  "output_format": {                  // Optional: Output format
    "type": "json_schema",            // "json_schema" | "json" | "markdown"
    "json_schema": {                  // Only for type: "json_schema"
      "summary": "string",
      "metrics": "object",
      "risks": "array",
      "recommendation": "string"
    }
  }
}

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-01-23T14:30:00Z",
  "estimated_duration_seconds": 60
}

GET /api/analysis/stock-report/jobs/{job_id}/status

Check the status of a running analysis

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",      // "pending" | "processing" | "completed" | "failed"
  "progress": 65,              // 0-100
  "phase": "analyzing",        // "collecting" | "analyzing" | "synthesizing"
  "rounds_completed": 2,       // Number of research rounds completed
  "created_at": "2025-01-23T14:30:00Z",
  "updated_at": "2025-01-23T14:30:45Z"
}

GET /api/analysis/stock-report/jobs/{job_id}/result

Retrieve analysis results (only when status: "completed")

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    // Structure depends on chosen output_format
    // json_schema: Exactly the requested structure
    // json: AI-optimized structure
    // markdown: Formatted text
  },
  "metadata": {
    "duration_seconds": 47,
    "rounds_completed": 3,      // Research rounds performed
    "tokens_used": 8420,
    "from_cache": false,        // true if from 7-day cache
    "cache_key": "abc123..."    // For cache management
  }
}

Portfolio Analysis Endpoints

POST /api/analysis/portfolio

Analyze a portfolio for risks and optimization opportunities

Request Body:

{
  "portfolio_composition": [
    {"symbol": "AAPL", "percentage": 30},    // Must sum to 100
    {"symbol": "MSFT", "percentage": 25},
    {"symbol": "GOOGL", "percentage": 20},
    {"symbol": "AMZN", "percentage": 15},
    {"symbol": "NVDA", "percentage": 10}
  ],
  "prompt": "Assess sector concentration and suggest alternatives",
  "output_format": {"type": "json_schema"}
}

Prompt Engineering Guide

Writing Effective Prompts

The quality of your analysis depends heavily on your prompt formulation. Our AI conducts multiple research rounds to answer your questions thoroughly.

Control Analysis Depth

Quick Analysis (1-2 rounds)

For time-sensitive decisions

"Quick take: How did the market react to Microsoft's earnings?"

Standard (3-4 rounds)

Balanced depth and speed

"Analyze Apple's services business: growth drivers, margins, and sustainability"

Deep Dive (5+ rounds)

Maximum research depth

"Conduct comprehensive due diligence on Tesla. Minimum 5 research rounds."

Prompt Patterns for Different Analysis Types

❌ Vague Prompts

"Analyze Apple"
"Is Microsoft a good investment?"
"Compare tech stocks"

Problem: No clear direction, wastes research capacity

✅ Targeted Prompts

"Analyze Apple's iPhone dependency. How successful is their services diversification?"
"Microsoft vs Google in cloud: Who has better growth prospects for enterprise AI?"
"Investigate Nvidia: Is the AI hype justified or is it overvalued?"

Benefit: Clear focus leads to relevant insights

Investigation Triggers

  • "Investigate why..." → Root cause analysis
  • "Find evidence that contradicts..." → Critical analysis
  • "Compare X to Y on..." → Focused comparison
  • "Test the thesis that..." → Hypothesis validation
  • "Identify risks that..." → Risk focus

Power Phrases

  • "Fundamental drivers"
  • "Competitive dynamics"
  • "Sustainable competitive advantages"
  • "Catalysts and risks"
  • "Valuation in historical context"

JSON Schema Best Practices

When using json_schema: Field order influences analysis quality. The AI builds context sequentially.

✅ Optimal Field Order

{
  "market_context": "string",      // Context first
  "fundamental_analysis": "object", // Then analysis
  "competitive_position": "object", // Comparisons
  "risks": "array",                // Challenges
  "opportunities": "array",        // Opportunities
  "recommendation": "string",      // Conclusion
  "confidence_level": "number"     // Meta information
}

❌ Suboptimal Order

{
  "recommendation": "string",      // Judgment without basis
  "confidence_level": "number",
  "risks": "array",
  "market_context": "string",      // Context too late
  "fundamental_analysis": "object" // Analysis at end
}

Automation

Set up recurring analyses that run automatically at scheduled times. Ideal for regular portfolio monitoring and systematic market surveillance.

One-Shot Analysis

Immediate execution via API for ad-hoc requests

  • • Earnings reactions
  • • Breaking news analysis
  • • Quick comparisons

Scheduled Analysis

Automatic execution on schedule

  • • Daily pre-market briefs
  • • Weekly portfolio reviews
  • • Monthly sector analysis

Popular Automation Patterns

Daily Market Brief

Mon-Fri, 6:00 AM EST

"Analyze major movements in my portfolio and identify new risks"

Weekly Deep Dive

Fridays, 6:00 PM EST

"Detailed weekly analysis: performance, news impact, and next week outlook"

Monthly Rebalancing

1st of month, 9:00 AM EST

"Portfolio optimization: identify overvalued positions and new opportunities"

Create Job Groups in Portal

Set Up Automation →

Use the web portal to set up recurring analyses. Define schedules, stock lists, and specific analysis prompts for automatic execution.

Troubleshooting & Optimization

Common Errors and Solutions

Invalid Symbol Error

Error: "Symbol XYZ123 not found"

Solution: Use valid ticker symbols only (e.g., AAPL, MSFT). For foreign stocks, use ADR symbols if available.

400

Rate Limit Exceeded

Monthly limit exceeded

Solution: Use caching (7 days), batch similar requests, or upgrade your plan.

429

Timeout Error

Analysis takes longer than 5 minutes

Solution: Reduce number of symbols or simplify prompt. Use status endpoint for progress updates.

504

Performance Optimization

✅ Best Practices

  • Use caching: Identical requests within 7 days
  • Batch requests: Multiple symbols in one request
  • Specific prompts: Clear focus = faster analysis
  • JSON Schema: Structured output for automation
  • Status polling: Check every 5-10 seconds

❌ Avoid

  • Redundant requests: Same analysis multiple times
  • Too many symbols: Max 10 per request
  • Vague prompts: "Analyze everything"
  • Excessive polling: Overloads the API
  • Ignoring cache: Wastes quota

Technical Specifications

Limits & Timeouts

Max symbols per request 10
Typical analysis duration 30-90s
Request timeout 5 min
Cache duration 7 days
Max prompt length 1000 chars

Response Codes

200 Success
400 Bad request
401 Unauthorized
429 Rate limit
500 Server error

Support & Resources

Developer Tools

Help & Contact

Ready for AI-powered financial analysis?