Skip to main content

​
Overview

The Chat API provides AI-powered financial analysis using a RAG (Retrieval-Augmented Generation) system. It searches across earnings transcripts, 10-K filings, and financial news to answer complex financial questions.

​
Stream Chat Message (Authenticated)

Stream an AI-generated response with real-time progress updates. Endpoint: POST /message/stream-v2 Authentication: Required 
curl -N -X POST https://api.financeagent.com/message/stream-v2 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What were Tesla'\'s revenue trends in Q4 2024?",
    "comprehensive": true,
    "conversation_id": null
  }'

​
Request Body

​
message
string
required
User question (max 1000 characters)
​
comprehensive
boolean
default:true
Whether to use comprehensive search (slower but more thorough)
​
conversation_id
string
Existing conversation ID to continue a thread (null for new conversation)

​
Streaming Response Events

The endpoint returns Server-Sent Events (SSE) in the following format: 
data: {"type": "event_type", "message": "...", "data": {...}}

​
Event Types

​
progress
event
Search and analysis progress updates
{"type": "progress", "message": "Searching earnings transcripts..."}
​
reasoning
event
AI reasoning steps during analysis
{"type": "reasoning", "message": "Analyzing Tesla Q4 2024 data"}
​
token
event
Streaming answer tokens (word-by-word)
{"type": "token", "data": {"token": "revenue"}}
​
result
event
Final complete answer with citations
{
  "type": "result",
  "conversation_id": "uuid",
  "data": {
    "response": {
      "answer": "Tesla's Q4 2024 revenue was $25.7B...",
      "citations": [
        {
          "company": "TSLA",
          "quarter": "2024_q4",
          "chunk_text": "Revenue for Q4 2024 was...",
          "relevance_score": 0.95,
          "citation_type": "transcript"
        }
      ]
    },
    "timing": {
      "total_time": 3.45,
      "search_time": 1.2,
      "generation_time": 2.25
    }
  }
}
​
error
event
Error during processing
{
  "type": "error",
  "message": "Rate limit exceeded",
  "error": "RATE_LIMIT_EXCEEDED"
}

​
Response Headers

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

​
Stream Demo Chat (Public)

Public demo endpoint with limited functionality. Endpoint: POST /landing/demo/stream-v2 Authentication: Not required
cURL
curl -N -X POST https://api.financeagent.com/landing/demo/stream-v2 \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is Apple'\'s market cap?",
    "comprehensive": false,
    "session_id": "demo-session-123"
  }'
​
message
string
required
User question
​
comprehensive
boolean
default:false
Search mode (limited in demo)
​
session_id
string
Client-generated session ID for rate limiting
Demo endpoint is limited to 5 messages per session and may have reduced functionality.

​
Get Chat History

Retrieve past chat messages with filtering and pagination. Endpoint: GET /history Authentication: Required
cURL
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://api.financeagent.com/history?limit=50&offset=0&search=Tesla"

​
Query Parameters

​
limit
integer
default:50
Maximum number of messages to return (max 100)
​
offset
integer
default:0
Number of messages to skip for pagination
​
search
string
Search term to filter messages
​
date_from
string
Filter messages from date (YYYY-MM-DD)
​
date_to
string
Filter messages to date (YYYY-MM-DD)

​
Response

​
success
boolean
Request status
​
messages
array
Array of chat history items
​
total_count
integer
Total number of messages

​
Get Chat Statistics

Retrieve chat usage statistics for the current user. Endpoint: GET /stats Authentication: Required
cURL
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.financeagent.com/stats

​
Response

​
success
boolean
Request status
​
stats
object
Usage statistics

​
Citation Types

The chat API returns citations from three sources:

​
Transcript Citations

{
  "citation_type": "transcript",
  "company": "AAPL",
  "year": 2024,
  "quarter": "2024_q4",
  "chunk_text": "Revenue increased 6% year over year...",
  "relevance_score": 0.92,
  "transcript_available": true
}

​
News Citations

{
  "citation_type": "news",
  "title": "Apple Reports Q4 Earnings Beat",
  "url": "https://news.example.com/apple-earnings",
  "published_date": "2024-11-01",
  "chunk_text": "Apple Inc. reported better than expected...",
  "relevance_score": 0.88
}

​
10-K Citations

{
  "citation_type": "10-K",
  "ticker": "MSFT",
  "fiscal_year": 2024,
  "section": "Risk Factors",
  "chunk_text": "Our business is subject to various risks...",
  "relevance_score": 0.85
}

​
Rate Limiting

Chat endpoints are subject to rate limits:
  • Authenticated: 20 requests/month (standard), 100 requests/month (admin)
  • Demo: 5 messages per session
When rate limited, you’ll receive an error event: 
{
  "type": "error",
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Monthly limit exceeded. Maximum 20 requests per month."
}

Build docs developers (and LLMs) love

Get started for freeTalk to us