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

​
Overview

Retrieve ranked document chunks for RAG (Retrieval-Augmented Generation) integration. This endpoint returns the top chunks after reranking, allowing you to merge them with your own LLM responses.

​
Request

​
query
string
required
The search query string
​
filters
object
Filter search results by specific criteria
​
top_k
number
default:10
Number of chunks to return (1-100)
​
rerank
boolean
default:true
Apply reranking to improve relevance of results

​
Request Example

curl -X POST https://api.fintool.com/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Tesla autonomous driving progress",
    "filters": {
      "tickers": ["TSLA"],
      "doc_types": ["10-K", "10-Q", "8-K", "EARNINGS_CALL"]
    },
    "top_k": 10,
    "rerank": true
  }'

​
Response

​
chunks
array
Array of document chunks matching the search query
​
total_chunks
number
Total number of chunks returned
​
processing_time_ms
number
Processing time in milliseconds

​
Response Example

{
  "chunks": [
    {
      "chunk_id": "TSLA_10K_2024_chunk_142",
      "document_title": "Tesla Inc. Form 10-K",
      "text": "Our Full Self-Driving (FSD) capability continues to improve with over 1.5 billion miles driven using FSD Beta. We are making significant progress toward achieving full autonomy through our end-to-end neural network approach...",
      "page_number": 28,
      "relevance_score": 0.96,
      "rerank_score": 0.94
    },
    {
      "chunk_id": "TSLA_EARNINGS_Q4_2024_chunk_89",
      "document_title": "Tesla Q4 2024 Earnings Call Transcript",
      "text": "Elon Musk: I'm highly confident that the car will be able to drive itself with reliability in excess of human this year. The rate of improvement is rapid...",
      "page_number": 12,
      "relevance_score": 0.94,
      "rerank_score": 0.92
    }
  ],
  "total_chunks": 2,
  "processing_time_ms": 450
}

​
Use Cases

RAG Integration

Use retrieved chunks as context for your own LLM to generate informed responses

Custom Pipelines

Build your own analysis workflows with relevant financial data

Hybrid Search

Combine with your proprietary data for comprehensive answers

Citation Building

Extract exact quotes and sources for financial research

​
RAG Integration Example

Here’s how to use the Search endpoint with your own LLM: 
import requests
import openai

# Step 1: Search for relevant chunks
search_url = "https://api.fintool.com/v1/search"
headers = {
    "Authorization": "Bearer YOUR_FINTOOL_API_KEY",
    "Content-Type": "application/json"
}

search_payload = {
    "query": "What is Tesla's autonomous driving strategy?",
    "filters": {"tickers": ["TSLA"]},
    "top_k": 5,
    "rerank": True
}

search_response = requests.post(search_url, headers=headers, json=search_payload)
chunks = search_response.json()["chunks"]

# Step 2: Build context from chunks
context = "\n\n".join([
    f"Source: {chunk['document_title']}\n{chunk['text']}"
    for chunk in chunks
])

# Step 3: Use with your own LLM
openai.api_key = "YOUR_OPENAI_API_KEY"

completion = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[
        {
            "role": "system",
            "content": "You are a financial analyst. Use the provided context to answer questions."
        },
        {
            "role": "user",
            "content": f"Context:\n{context}\n\nQuestion: What is Tesla's autonomous driving strategy?"
        }
    ]
)

print(completion.choices[0].message.content)

​
Reranking

When rerank: true is set, the API applies a two-stage retrieval process:
1

Initial Retrieval

Vector similarity search retrieves candidate chunks
2

Reranking

A reranking model scores candidates for better relevance
3

Top-K Selection

Returns the top K chunks based on rerank scores
Reranking significantly improves result quality but adds ~200ms latency. Disable for faster responses when speed is critical.

​
Filtering Best Practices

Always include ticker symbols when searching for company-specific information to reduce noise and improve relevance.
  • Use 10-K for annual comprehensive data
  • Use 10-Q for quarterly updates
  • Use EARNINGS_CALL for management commentary
  • Use 8-K for material events
Specify date ranges to focus on recent or historical information:
"dates": {
  "start": "2024-01-01",
  "end": "2024-12-31"
}

​
Error Responses

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