Navigation

API Documentation

Integrate Fintool's financial analysis capabilities into your applications

API Status: Operational

Version 2.0

Base URL

https://api.fintool.com

Support

Contact Support

Overview

The Fintool API provides access to our advanced financial analysis capabilities through a simple REST interface. Our API processes natural language queries about public companies and returns comprehensive answers backed by authoritative financial documents including SEC filings, earnings transcripts, and financial statements.

Key Features

What makes our API powerful for financial analysis

Comprehensive Data Coverage

Access to SEC filings, earnings transcripts, and financial statements

Real-time Streaming

Get responses as they're generated with Server-Sent Events

Citation Support

All answers include citations to original source documents

Session Management

Maintain conversation context across multiple requests

Authentication

All API requests require authentication using an API key. Include your API key in theAuthorization header using the Bearer scheme.

Authentication Example

BASH

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

Contact our sales team to get access to the Fintool API and receive your authentication credentials.

Request API Access

POST /v2/chat

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

Request Body Parameters

Parameter	Type	Required	Description
`messages`	array	Required	Conversation history. Each element contains 'role' (user/assistant) and 'content' (string)
`stream`	boolean	Optional	If true, response is streamed via Server-Sent Events. Default: false

Request Headers

Parameter	Type	Required	Description
`Authorization`	string	Required	Bearer token with your API key
`X-Conversation-ID`	string	Optional	Idempotency key for conversation tracking (debugging)
`X-Round-ID`	string	Optional	Idempotency key for individual request (debugging)

Request Example

cURL Request

BASH

curl -X POST https://api.fintool.com/v2/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Conversation-ID: optional-conversation-id" \
  -H "X-Round-ID: optional-round-id" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What was Tesla's revenue in Q4 2024?"
      }
    ],
    "stream": false
  }'

Response Format

For non-streaming requests, the API returns a single JSON object. The response includes the assistant's message with citations to source documents.

Response Example

JSON

{
  "id": "msg_abc123",
  "createdAt": "2025-01-21T18:25:09Z", 
  "type": "message",
  "message": {
    "role": "assistant",
    "content": "Tesla's Q4 2024 revenue was $25.2 billion, representing a 2% increase year-over-year **[tesla_10k_2024_revenue]**",
    "metadata": {
      "session_data": "eyJzZXNzaW9uX2lkIjoi..."
    }
  }
}

Message Object Fields

Parameter	Type	Required	Description
`role`	string	Required	Always 'assistant' for responses
`thinking`	string	Optional	Shows the AI's reasoning process (streaming only)
`content`	string	Required	The response content with citations in [chunk_id] format
`metadata`	object	Optional	Contains session_data (base64 string) to include in next request

Streaming Responses

Enable real-time response streaming by setting stream: true. The API will send Server-Sent Events as the response is generated, allowing you to display partial results immediately.

Streaming Request

Streaming cURL Example

BASH

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": "Analyze Microsoft's latest earnings"
      }
    ],
    "stream": true
  }' \
  --no-buffer

Streaming Response

Server-Sent Events

TEXT

event: message
data: {
  "id": "msg_abc123",
  "createdAt": "2025-01-21T18:23:05Z",
  "type": "message", 
  "message": {
    "role": "assistant",
    "thinking": "Searching for Microsoft earnings data...",
    "content": "Let me analyze Microsoft's latest earnings report..."
  }
}

event: message  
data: {
  "id": "msg_abc124",
  "createdAt": "2025-01-21T18:23:08Z",
  "type": "message",
  "message": {
    "role": "assistant", 
    "content": "Microsoft reported strong Q2 2025 results with revenue of $69.6 billion **[msft_earnings_q2_2025]**",
    "metadata": {
      "session_data": "eyJzZXNzaW9uX2lkIjoi..."
    }
  }
}

Event Types

message Event

Contains incremental response data. Multiple events are sent as the response is generated.

error Event

Sent if an error occurs during processing. Contains errorMessage and statusCode fields.

Error Response

Error Event Example

JSON

{
  "id": "err_abc123",
  "created": "2025-01-21T18:25:09Z",
  "type": "error", 
  "errorMessage": "Invalid API key provided",
  "statusCode": "AUTH_INVALID_API_KEY"
}

Code Examples

JavaScript / Node.js

JavaScript Example

JAVASCRIPT

const response = await fetch('https://api.fintool.com/v2/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Conversation-ID': 'optional-conversation-id'
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        content: 'What was Apple's gross margin in 2024?'
      }
    ],
    stream: false
  })
});

const data = await response.json();
console.log(data.message.content);

Python

Python Example

PYTHON

import requests

url = "https://api.fintool.com/v2/chat"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "X-Conversation-ID": "optional-conversation-id"
}

payload = {
    "messages": [
        {
            "role": "user", 
            "content": "Summarize Amazon's latest 10-K filing"
        }
    ],
    "stream": False
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(data["message"]["content"])

Best Practices

Tips for optimal API usage

Include session_data

Always return the session_data from previous responses to maintain conversation context and improve response quality.

Use streaming for better UX

Enable streaming to show real-time progress and thinking, improving perceived response time.

Handle citations properly

Parse citation markers **[chunk_id]** to provide users with links to source documents.

Ready to Get Started?

Contact our team to get API access and start integrating Fintool's powerful financial analysis capabilities into your applications.

Request API Access Learn More