Skip to main content
POST
https://api.fintool.com
/
v2
/
chat
POST /v2/chat
curl --request POST \
  --url https://api.fintool.com/v2/chat
{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: messages"
  }
}

​
Overview

The primary endpoint for sending financial analysis queries. Send a conversation history and receive intelligent responses backed by comprehensive financial data with citations.

​
Request

​
messages
array
required
Conversation history with role and content
​
stream
boolean
default:false
Enable Server-Sent Events streaming for real-time responses
​
filters
object
Filter results by specific criteria
​
include_citations
boolean
default:true
Include detailed citation information in the response

​
Request Example

curl -X POST https://api.fintool.com/v2/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What was Tesla'\''s revenue in Q4 2024?"
      }
    ],
    "stream": false,
    "filters": {
      "tickers": ["TSLA"],
      "doc_types": ["10-K", "10-Q", "8-K"]
    }
  }'

​
Response

​
id
string
Unique identifier for the message
​
createdAt
string
ISO 8601 timestamp of when the message was created
​
type
string
The type of response, typically "message"
​
message
object
The assistant’s response message
​
citations
array
Array of citation objects providing source information

​
Response Example

{
  "id": "msg_abc123",
  "createdAt": "2025-01-21T18:25:09Z",
  "type": "message",
  "message": {
    "role": "assistant",
    "content": "Tesla's Q4 2024 revenue was $25.2 billion **[tesla_10k_2024_revenue]**",
    "metadata": {
      "session_data": "eyJzZXNzaW9uX2lkIjoi..."
    }
  },
  "citations": [
    {
      "chunk_id": "tesla_10k_2024_revenue",
      "document_title": "Tesla Inc. Form 10-K",
      "page_number": 42,
      "relevance_score": 0.95
    }
  ]
}

​
Multi-turn Conversations

To maintain conversation context across multiple requests, include the session_data from the previous response in your message metadata: 
{
  "messages": [
    {
      "role": "user",
      "content": "What was Tesla's revenue in Q4 2024?"
    },
    {
      "role": "assistant",
      "content": "Tesla's Q4 2024 revenue was $25.2 billion **[tesla_10k_2024_revenue]**",
      "metadata": {
        "session_data": "eyJzZXNzaW9uX2lkIjoi..."
      }
    },
    {
      "role": "user",
      "content": "How does that compare to Q3?"
    }
  ]
}
Always include the session_data from previous responses to maintain conversation context and get more accurate answers.

​
Handling Citations

Citation markers appear in the content as **[chunk_id]**. Parse these to:
  1. Extract the chunk_id
  2. Find the corresponding citation in the citations array
  3. Display source information to users
  4. Link to the original document
Example parsing: 
import re

content = response['message']['content']
citations_map = {c['chunk_id']: c for c in response['citations']}

# Find all citation markers
citation_ids = re.findall(r'\*\*\[([^\]]+)\]\*\*', content)

for cid in citation_ids:
    citation = citations_map.get(cid)
    if citation:
        print(f"Source: {citation['document_title']}, Page {citation['page_number']}")

​
Error Responses

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: messages"
  }
}