# Authentication
Source: https://docs.stockinsights.ai/api-reference/authentication
How to authenticate requests to the API.
## Welcome
Each request to the API must be authenticated with a valid API key.
### Getting your API key
Once you signup to your account, you can navigate to "API access" section under "Account Settings" to generate your API key.
![]()
If you need a custom API end-point, please send your request - [Request Form](https://airtable.com/appwmCiMxABL5dAtH/shrJoJJnvXDkbaXHf).
### Access Control
All API endpoints are authenticated using Authorization header and your dedicated API key.
```json theme={null}
'Authorization': 'Bearer '
```
# Announcements Tagged Feed
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/announcements-tagged-feed
openapi-india get /api/in/v0/documents/announcement
The Announcements Tagged Feed API delivers a real-time stream of Corporate filings disclosed to BSE/NSE exchanges, each tagged with AI-generated insights including summaries, category tags (drawn from a predefined set of categories), and sentiment tags. Users can utilize this tagged feed to monitor daily updates on material events reported by companies, enabling them to build custom email notification systems or display widgets for tracking significant corporate disclosures in their apps.
# Balance Sheet
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/balance-sheet
openapi-india get /api/in/v0/financial-statements/balance-sheet
Retrieve a structured balance sheet for an Indian company. By default, this returns the latest consolidated balance sheet from a half-yearly filing. Balance-sheet facts remain point-in-time (`reporting_type: as_of`); the optional `reporting_type` query parameter selects the source filing cadence. The financials structure is selected by the returned profile: bank, nonbank, life_insurance, general_insurance, or investment_trust.
Enter a company ticker to get its latest consolidated balance sheet from a
half-yearly filing. You only need to provide a date, filing cadence, or scope
when you want something different.
For example, a request with only `ticker=RELIANCE` uses:
* Latest available period
* `reporting_type=half_yearly` for selecting the filing
* `statement_scope=consolidated`
A balance sheet is a point-in-time statement, so the response continues to show
`reporting_type: "as_of"`. Use `period_end_date` for an exact historical result;
common reporting-period dates are `2025-03-31`, `2025-06-30`, `2025-09-30`,
and `2025-12-31`. Availability depends on the selected filing cadence, and
existing exact-date requests do not need to add one.
# Cash Flow Statement
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/cash-flow
openapi-india get /api/in/v0/financial-statements/cash-flow
Retrieve a structured cash flow statement for an Indian company. By default, this returns the latest consolidated half-yearly result. Supply optional period, reporting type, or scope parameters for a different statement. The financials structure is selected by the returned profile: bank, nonbank, life_insurance, general_insurance, or investment_trust.
Enter a company ticker to get its latest consolidated half-yearly cash flow
statement. You only need to provide a date, reporting type, or scope when you
want something different.
For example, a request with only `ticker=RELIANCE` uses:
* Latest available period
* `reporting_type=half_yearly`
* `statement_scope=consolidated`
Use `period_end_date` for an exact historical result. Common reporting-period
dates are `2025-03-31`, `2025-06-30`, `2025-09-30`, and `2025-12-31`.
Availability depends on the selected reporting type.
# Companies List
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/companies
openapi-india get /api/in/v0/companies
Returns a paginated list of India-listed companies with identifiers (ISIN, BSE, NSE) and industry classification. Supports filtering by ticker, sector, industry, market-cap category, and company ID. Defaults to sort by `company_name` ascending.
# Filings Embeddings Search
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/filings-embeddings-search
openapi-india post /api/in/v0/documents/embeddings-search
The Filings Embeddings Search API retrieves the nearest chunks of text (based on semantic similarity) from our database for specified filings (earnings transcripts and annual reports) for any given user query/prompt in natural langauge. Users can utilize this functionality for various purposes, such as building an AI-search engine, AI-tagging, etc., using the associated text from these filings.
# Filings Feed
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/filings-feed
openapi-india get /api/in/v0/documents
The Filings Feed API retrieves real-time updates on earnings call transcripts and other corporate filings (e.g., Annual Reports, Investor Presentations, Corporate Announcements) published on the BSE/NSE exchanges based on the specified document type. Users can optionally filter results by sector, timeframe, or other parameters to facilitate targeted information retrieval.
# Filings Keyword Search
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/filings-keywords-search
openapi-india post /api/in/v0/documents/full-text-search
The Filings Keyword Search API fetches search results from our database for specified filings (earnings transcripts and annual reports) for any given keyword/phrase. Returns upto 100 search results sorted by latest date
# Income Statement
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/income-statement
openapi-india get /api/in/v0/financial-statements/income-statement
Retrieve a structured income statement (profit & loss) for an Indian company. By default, this returns the latest consolidated quarterly result. Supply optional period, reporting type, or scope parameters for a different statement. The financials structure is selected by the returned profile: bank, nonbank, life_insurance, general_insurance, or investment_trust.
Enter a company ticker to get its latest consolidated quarterly income
statement. You only need to provide a date, reporting type, or scope when you
want something different.
For example, a request with only `ticker=RELIANCE` uses:
* Latest available period
* `reporting_type=quarterly`
* `statement_scope=consolidated`
Use `period_end_date` for an exact historical result. Common reporting-period
dates are `2025-03-31`, `2025-06-30`, `2025-09-30`, and `2025-12-31`.
Availability depends on the selected reporting type.
# Results Calendar API
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/results-calendar
openapi-india get /api/in/v0/results-calendar
Returns the latest paginated results calendar for listed Indian companies, optionally filtered by ticker.
# Segment Results
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/segment-results
openapi-india get /api/in/v0/financial-statements/segment-results
See how each of a company’s businesses contributes to revenue and profit. By default, this returns the latest consolidated quarterly result. Some filings also report assets, liabilities, and capital employed by business.
See how each of a company’s businesses contributes to revenue and profit. Some
filings also report assets, liabilities, and capital employed by business.
Enter a company ticker to get its latest consolidated quarterly segment result.
You only need to provide a date, reporting type, or scope when you want
something different.
For example, a request with only `ticker=RELIANCE` uses:
* Latest available period
* `reporting_type=quarterly`
* `statement_scope=consolidated`
Use `period_end_date` for an exact historical result. Common reporting-period
dates are `2025-03-31`, `2025-06-30`, `2025-09-30`, and `2025-12-31`.
Availability depends on the selected reporting type.
All financial values are in ₹ crores. The `profile` field identifies the type of
company and helps you understand which sections to expect.
## What each company type reports
| Company type | What you will usually see |
| --------------------------- | ------------------------------------------------------------------------ |
| Regular companies and banks | Revenue, profit, and available assets, liabilities, and capital employed |
| Life insurers | Assets, liabilities, and capital employed |
| General insurers | Revenue and operating profit |
| REITs and InvITs | Revenue, profit, and meaningful position data where reported |
## Reading the financial sections
* `segments`: values for each business reported by the company.
* `adjustments`: eliminations or reconciliation amounts outside named
businesses.
* `inter_segment_revenue`: sales between the company’s businesses.
* `un_allocable`: position amounts that the company did not assign to a
business.
* `total`: the reported total, or a total calculated only when the available
data supports a meaningful result.
## Understanding missing values
* `0` means the filing reported zero, or the available values genuinely
calculate to zero.
* `null` means the field is relevant, but the filing does not provide enough
information for a meaningful value.
* A missing section means that section is not used for that type of company.
# Shareholding Pattern Holders
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/shareholding-holders
openapi-india get /api/in/v0/shareholding/pattern/holders
Drill into disclosed holder rows from one canonical shareholding filing. By default, the latest periodic snapshot is selected. Use filing_basis to select a different filing type and as_of_date to select an exact observation. Category and holder-name filters are applied after selecting the snapshot and before pagination. Shares and percentages are independently source-reported values, and a holder category may be null when the source taxonomy cannot be mapped confidently.
Use this endpoint to inspect disclosed holder rows from one canonical filing
selected using the same snapshot controls as the
[Shareholding Pattern](/api-reference/india_endpoints/shareholding-pattern)
endpoint.
## Choose the filing and holders
* `filing_basis` selects `periodic`, `pre_listing`, or
`capital_restructuring`, and defaults to `periodic`.
* For periodic holders, `as_of_date` selects an exact quarter-end observation.
Common dates are `2025-03-31`, `2025-06-30`, `2025-09-30`, and
`2025-12-31`.
* Without `as_of_date`, the endpoint uses the latest canonical filing for the
selected basis.
* If you provide `as_of_date` without `filing_basis`, the request still defaults
to `periodic`.
To inspect a non-periodic filing, select `filing_basis=pre_listing` or
`filing_basis=capital_restructuring` and initially omit `as_of_date`; the
endpoint selects the latest filing for that basis. Add a date only when you
know the exact observation you want. The API does not substitute an earlier or
later observation when the requested date has no exact match.
After selecting the filing, narrow its disclosed rows with:
* `category` for one of `promoters`, `fii`, `dii`, `government`, or `public`.
* `q` for a case-insensitive substring search within holder names.
* `page` and `limit` to paginate the matching rows.
For example, use `ticker=JAKHARIA`,
`filing_basis=capital_restructuring`, and `as_of_date=2025-10-09` to
inspect holders disclosed after that capital-structure change.
Category and name filters are applied before pagination. The default page is
`1`, the default limit is `50`, and the maximum limit is `100`.
## Reading the response
* `total_shares` and `total_shareholders` describe the entire filing, not just
the holders on the current page.
* `as_of_date` and `filing_basis` identify the selected filing.
* `meta.total_count` is the number of disclosed holder rows matching your
filters before pagination. It is not the company’s total shareholder count.
* `shares` and `percentage` are independently reported for each holder. Keep
both when exact share counts matter.
* `category` is the stable headline classification used by the API.
* `subcategory` is a more detailed taxonomy-derived classification and may
evolve as regulatory taxonomies change.
A holder’s `category` can be `null` when the row does not map to one of the five
headline categories. This does not necessarily mean the source classification
is missing; use `subcategory` for the available detail.
This endpoint returns disclosed filing rows, not a complete register of every
shareholder. If no canonical filing matches the selected basis and date, `data`
is `null` and `meta.total_count` is `0`. If the filing exists but no holder rows
match your filters, the filing metadata remains available, `holders` is empty,
and `meta.total_count` is `0`.
# Shareholding Pattern History
Source: https://docs.stockinsights.ai/api-reference/india_endpoints/shareholding-pattern
openapi-india get /api/in/v0/shareholding/pattern
Retrieve canonical shareholding patterns for an Indian company. By default, the response contains the latest eight periodic observations, newest first. Use filing_basis to select pre-listing or capital-restructuring filings, and as_of_date to select an exact observation date. Headline percentages and total shares are independently source-reported values, so percentages may not sum to exactly 100 and cannot be used to reconstruct exact share counts. Missing categories and unavailable totals are returned as null.
Use this endpoint to see how a company’s ownership is divided among promoters,
foreign institutional investors (FII), domestic institutional investors (DII),
government entities, and the public.
Enter a company ticker, such as `RELIANCE`. By default, the endpoint returns up
to eight canonical periodic observations, ordered from newest to oldest.
## Choose which patterns to return
* `filing_basis` selects the reason for the filing and defaults to `periodic`:
* `periodic` is a regular reporting-period disclosure.
* `pre_listing` is a disclosure made before the company’s listing.
* `capital_restructuring` follows a material change in the company’s capital
structure.
* For periodic patterns, `as_of_date` selects an exact quarter-end observation.
Common dates are `2025-03-31`, `2025-06-30`, `2025-09-30`, and
`2025-12-31`.
* If you provide `as_of_date` without `filing_basis`, the request still defaults
to `periodic`.
To explore non-periodic history, select `filing_basis=pre_listing` or
`filing_basis=capital_restructuring` and initially omit `as_of_date`. Add a date
only when you know the exact observation you want. For example, use
`ticker=DANGEE`, `filing_basis=pre_listing`, and `as_of_date=2018-09-01` to
retrieve Dangee Dums’ pre-listing observation.
The response always uses the same collection shape. A request without an exact
date can return up to eight observations. An exact-date request returns zero or
one canonical observation. The API does not substitute an earlier or later
observation when the requested date has no exact match.
## Reading the response
* `data.patterns` contains the matching observations, newest first.
* `as_of_date` is the observation date reported for each filing.
* `filing_basis` identifies why that filing was submitted.
* `total_shares` is the total share count reported in that observation.
* `total_shareholders` is the observation’s reported number of shareholders.
It may be `null` when the source does not provide it.
* Values under `shareholding` are source-reported percentage points for each
headline category.
Share counts and percentages are independently source-reported values.
Percentages may not sum to exactly 100 because of rounding, missing categories,
or regulatory classifications.
## Understanding missing values
* `0` means the filing reported zero for that category.
* `null` means the value was unavailable or could not be mapped to that
headline category.
* `patterns: []` means the ticker identifies a valid company, but no canonical
observation exactly matches the selected filing basis and date.
To inspect the disclosed holders behind the headline categories, use the
[Shareholding Pattern Holders](/api-reference/india_endpoints/shareholding-holders)
endpoint.
# Contextual Search
Source: https://docs.stockinsights.ai/api-reference/sample_scripts/contextual-search
How to use Embeddings API for performing Contextual Search.
To use the Vector Database, please go through the detailed information from the [Embeddings API Documentation](https://docs.stockinsights.ai/api-reference/india_endpoints/filings-embeddings-search).
If you don't have an API key, generate one from the dashboard [Getting your API key to authenticate requests](https://docs.stockinsights.ai/api-reference/authentication).
## Example
Below is a Python example demonstrating how to make a request to the API to perform a contextual search:
```python theme={null}
import requests
import json
def retrieve_similar_filings_chunks(query):
url = 'https://stockinsights-ai-main-49970eb.d2.zuplo.dev/api/in/v0/documents/embeddings-search'
headers = {'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY_HERE'}
data = {
"query": query,
"filters": {
"types": ["earnings-transcript", "annual-report"],
'year': '2024'
}
}
response = requests.post(url, headers=headers, data=json.dumps(data))
return response.json()
result = retrieve_similar_filings_chunks("FIIs contribution to Indian Capital Markets")
```
## Key Points
* Replace YOUR\_API\_KEY\_HERE with your actual API key in the Authorization header.
* Modify the query parameter to suit your search needs.
* Adjust the filters to target specific document types or time periods.
# Question Answering
Source: https://docs.stockinsights.ai/api-reference/sample_scripts/question-answering
How to use Embeddings API for Natural Language Question Answering via any LLM
To use the Embeddings API, please go through the detailed information about the API and its parameters from the [Documentation](https://docs.stockinsights.ai/api-reference/india_endpoints/filings-embeddings-search).
If you don't have an API key, generate one from the dashboard [Getting your API key to authenticate requests](https://docs.stockinsights.ai/api-reference/authentication).
## Example
Below is a Python example demonstrating how to perform a question-answering:
### Function to get similar filings chunks
```python theme={null}
import requests
import json
def retrieve_similar_filings_chunks(query):
url = 'https://stockinsights-ai-main-49970eb.d2.zuplo.dev/api/in/v0/documents/embeddings-search'
headers = {'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY_HERE'}
data = {
"query": query,
"filters": {
"types": ["earnings-transcript", "annual-report"],
'year': '2024'
}
}
response = requests.post(url, headers=headers, data=json.dumps(data))
return response.json()
result = retrieve_similar_filings_chunks("FIIs contribution to Indian Capital Markets")
```
### Function to Generate Answers Using OpenAI GPT Model
```python theme={null}
from openai import OpenAI
# Set your OpenAI API key
client = OpenAI(
api_key='YOUR_OPEN_AI_KEY_HERE',
)
GPT_MODEL = 'gpt-4o-mini'
# To interact with OpenAI GPT model
def chat_completion_request(messages, model= GPT_MODEL, stream=False, functions=None, function_call=None):
try:
response = client.chat.completions.create(
model=model,
messages=messages,
stream = stream,
functions=functions,
function_call=function_call
)
return response
except Exception as e:
print("Unable to generate ChatCompletion response")
print(f"Exception: {e}")
return e
# Function to construct knowledge source
def construct_knowledge_source(similar_chunks):
knowledge_source = ""
data = similar_chunks.get('data', [])
for entry in data:
chunk_content = entry.get('text', '')
company_name = entry.get('company', {}).get('company_name', '')
document_type = entry.get('document', {}).get('type', '')
document_link = entry.get('document', {}).get('link', '')
page_num = entry.get('metadata', {}).get('page_num', '')
document_link_with_page = f"{document_link}#page={page_num}"
year = entry.get('document', {}).get('year', '')
quarter = entry.get('document', {}).get('quarter', '')
# Append the context to each chunk
knowledge_source += f"This is a section from {document_type} of company {company_name} for FY{year} {quarter if quarter else ''} from {document_link_with_page}: {chunk_content};\n\n"
return knowledge_source
def get_answer_from_public_company_filings(query):
similar_filings_chunks = retrieve_similar_filings_chunks(query)
knowledge_source = construct_knowledge_source(similar_filings_chunks)
response_instructions = """
Answer user questions based on some parts of the filings/disclosures identified as most relevant to the question.
Provide a clear and comprehensive response to the question only from the provided context. """
setup_messages=[
{'role': 'system',
'content': response_instructions
},
{
'role': 'system',
'content': knowledge_source
},
{'role': 'user',
'content': query
}
]
chat_response = chat_completion_request(messages = setup_messages,stream = False)
message = chat_response.choices[0].message.content
return message
query = 'What could be the reasons for decreased overseas(FII) contribution in Indian Capital Markets decreasing while the Domestic fund flows contributions are increasing'
get_answer_from_public_company_filings(query)
```
## Key Points
* Replace YOUR\_API\_KEY\_HERE with your actual API key in the Authorization header.
* Replace YOUR\_OPEN\_AI\_KEY\_HERE with your actual OpenAI API key.
* Modify the query parameter to suit your specific question.
* Adjust the filters to target specific document types or time periods as needed.
# 8-K/6-K Tagged Feed
Source: https://docs.stockinsights.ai/api-reference/us_endpoints/8k-6k-tagged-feed
openapi-us get /api/us/v0/documents/announcement
The API returns the latest 8-K and 6-K feed from SEC Edgar, each tagged with AI-generated insights including summaries, category tags (drawn from a predefined set of categories), and sentiment tags. Users can utilize this tagged feed to monitor daily updates on material events reported by companies, enabling them to build custom email notification systems or display widgets for tracking significant corporate disclosures in their apps.
# Balance Sheet
Source: https://docs.stockinsights.ai/api-reference/us_endpoints/balance-sheet
openapi-us get /api/us/v0/financial-statements/balance-sheet
Retrieve an as-reported balance sheet for a US issuer by SEC CIK and period end date. Resolves across 10-Q, 10-K, and 20-F filings (including amendments), preferring the original filing that first reported the period. Balance sheets are point-in-time snapshots; reporting_type in the response is always 'instant'.
# Cash Flow Statement
Source: https://docs.stockinsights.ai/api-reference/us_endpoints/cash-flow
openapi-us get /api/us/v0/financial-statements/cash-flow
Retrieve an as-reported cash flow statement for a US issuer by SEC CIK, period end date, and reporting type. Resolves across 10-Q, 10-K, and 20-F filings (including amendments), preferring the original filing that first reported the period.
# Companies List
Source: https://docs.stockinsights.ai/api-reference/us_endpoints/companies
openapi-us get /api/us/v0/companies
Returns a paginated list of US-listed companies with identifiers (CIK, ticker), exchange information, and industry classification. Supports filtering by ticker, CIK, sector, industry, market-cap category, and company ID. Defaults to sort by `company_name` ascending.
# Filings Embeddings Search
Source: https://docs.stockinsights.ai/api-reference/us_endpoints/filings-embeddings-search
openapi-us post /api/us/v0/documents/embeddings-search
The Filings Embeddings Search API retrieves the nearest chunks of text (based on semantic similarity) from our database for specified filings (earnings transcripts and 10-Ks) for any given user query/prompt in natural langauge. Users can utilize this functionality for various purposes, such as building an AI-search engine, AI-tagging, etc., using the associated text from these filings.
# Filings Feed
Source: https://docs.stockinsights.ai/api-reference/us_endpoints/filings-feed
openapi-us get /api/us/v0/documents
The Filings Feed API retrieves real-time updates on earnings call transcripts and SEC filings (e.g., 10-K, 10-Q, 8-K) based on the specified document type. Users can optionally filter results by sector, timeframe, or other parameters to facilitate targeted information retrieval.
# Income Statement
Source: https://docs.stockinsights.ai/api-reference/us_endpoints/income-statement
openapi-us get /api/us/v0/financial-statements/income-statement
Retrieve an as-reported income statement for a US issuer by SEC CIK, period end date, and reporting type. Resolves across 10-Q, 10-K, and 20-F filings (including amendments), preferring the original filing that first reported the period.
# AI Assist
Source: https://docs.stockinsights.ai/features/ai-assist
Your Intelligent Filing Research Companion
## Overview
Imagine having the ability to query filings with natural language to fetch key information in a precise manner.
That's what the AI-Assist feature does and beyond.
## Key Benefits
1. Natural Language Queries: Use simple, everyday language to ask questions about filings and receive accurate, relevant answers.
2. Intuitive Chat Interface: Interact with filings through our user-friendly chat interface, making your research process easier and more efficient.
3. Simplified Research: No need to sift through lengthy documents manually. Get the information you need quickly and accurately.
## How AI-Assist Works
1. Source-Specific Responses: Unlike Chat-GPT, AI-Assist answers only from the underlying sources, not the open internet. This ensures that the information is highly relevant and accurate. Additionally, the sources are shown below each response, allowing you to further deep-dive into the original documents.
2. Daily Updates: The underlying sources are updated daily with the latest filings released by companies, ensuring you always have access to the most current data.
## How to Use AI-Assist
1. Enter Your Query: Type your question or query in natural language into the chat interface.
2. Receive Answers: Get precise information pulled directly from the filings. Each response includes links to the original source documents, allowing you to read more and verify the information.
3. Refine Your Search: Use filters to refine your search by timeline, companies, and filing types to narrow down the results and find exactly what you need.
4. Follow-Up Questions: If needed, ask follow-up questions to gather more detailed insights and continue your research seamlessly.Tips for Effective Use
Be Specific: The more specific your query, the more precise the response.
## FAQs
Q: Can AI-Assist handle complex queries?
A: Yes, AI-Assist is designed to understand and process complex queries. It leverages RAG based model to retrieve the most relevant content from the filings and respond to the question in the context.
# Announcements Tracker
Source: https://docs.stockinsights.ai/features/announcements-tracker
Stay Updated on Company Updates with Smart Classifications
## Overview
Effortlessly stay updated on company developments with our intelligent announcements filing feed.
## Key Benefits
1. Smart Classification: The feature employs intelligent classification to automatically categorize and label filings based on their content. This provides you with an organized and structured view of the information, facilitating easier navigation and analysis.
2. Filter Noise: By intelligently filtering out irrelevant filings, the feature helps you focus on the most pertinent updates and disclosures, reducing noise.
3. Notifications: Tailor the monitoring and alert system to your specific interests and requirements, enabling you to receive notifications for updates from specific companies and filing types, keeping you informed about the developments that matter most to you.
## How Announcements Tracker Works
1. Smart Classification: The system analyzes the content of filings and automatically categorize them into pre-defined categories, based on content similarity.
2. Noise Filtering: The feature filters out non-essential filings, ensuring that you only see updates that are significant.
## How to Use Announcements Tracker
1. Add to Watchlist & Setup Notifications: You can tailor the notifications to your specific watchlist stocks, enabling you to receive email updates from specific companies.
# Email Notifications
Source: https://docs.stockinsights.ai/features/email-alerts
Stay Informed with Email Alerts
## Overview
Stay on top of important updates by adding stocks to your watchlist and receiving customized email notifications.
## Key Benefits
1. Custom Watchlist: Add stocks to your watchlist to monitor specific companies.
2. Tailored Notifications: Choose the types of filings you want to be notified about, ensuring you receive only the updates that matter to you.
3. Timely Updates: Receive email notifications with the latest updates on your selected stocks and filing types.
# AI Generated Summaries
Source: https://docs.stockinsights.ai/features/filings-ai-insights
Effortless Insights from Earnings Calls and Annual Reports
## Overview
Navigate through Earnings Calls Transcripts & Annual Reports with AI-crafted summaries.
## Key Benefits
1. Enhanced Readability: The summaries present complex information from filings and transcripts in a concise and easily digestible format, enhancing readability and making it more efficient to grasp key insights without getting bogged down by extensive technical details.
2. Grasp Key Takeaways: Key topics and areas are identified and separated within the AI-generated summaries, allowing you to quickly grasp the crucial takeaways and focus on the most pertinent information.
3. Identify Changes from Past Disclosures: By comparing the current summaries with past disclosures, you can easily identify and track changes in a company's risk factors, financial performance, or strategic outlook, facilitating better-informed decision-making.
## How AI-Generated Summaries Work
1. Summary-Generation: The LLMs are fed the long-form content of the filings, extracting relevant information and key points.
2. Prompt-Based: Utilizing a predefined prompt, the the LLM organizes it into a structured and concise summary. This ensures that the most important details and insights from the documents are highlighted effectively.
## How to Use AI-Generated Summaries
1. Read the Long-Form Content: For a more in-depth understanding of the topic, please refer to the full transcripts and reports.
2. Upcoming Features:
a. Citations: In future versions, we will provide citations for each section, allowing you to easily refer to the original content.
b. Custom Prompts: You will also have the ability to create and save your own prompts to generate personalized summaries based on your specific needs.
## FAQs
Q: How accurate are the AI-generated summaries?
A: The AI-generated summaries are based on LLMs and are designed to summarize only based on the underlying transcripts/annual reports. However, we have observed that in rare cases, there is a possibility of hallucinations. We are actively working towards auto-identifying these from our end, but we request you to report any inaccuracies when found.
# Search Filings
Source: https://docs.stockinsights.ai/features/filings-search
Efficiently Find Key Financial Information
## Overview
The Search Filings feature allows you to effectively perform keyword searches or multi-keyword searches across all filings, helping you quickly locate key financial information. This powerful tool is designed to meet both basic and advanced search needs.
#### Key Benefits
1. Keyword and Multi-Keyword Search: Easily search for specific terms or phrases within filings to find relevant information quickly.
2. Advanced Filters: Use filters to refine your search results by timeline, companies, and filing types, allowing you to narrow down the scope to meet your specific needs.
3. Access to Source Filings: Click on the search results to access the original source filings, enabling you to read more and verify the details.
# Getting Started
Source: https://docs.stockinsights.ai/getting-started
Learn how you can use stockinsighs.ai in your investment journey
### Signing Up
Signing up for stockinsights.ai is quick and easy. Simply visit our website and click on the "Sign Up" button. You'll be prompted to enter your email address, and a verification link will be sent to your email to confirm your account. Click on the link in the email, and you're all set to start exploring the platform!
### Setting Up Your Profile
After signing up, you'll be prompted to set up your profile and select your market of interest—either US or India. It's essential to choose the one that aligns with your investment focus, as the data and tools specific to the filings will vary accordingly. You can always navigate to the "Profile" section to update your personal information and preferences in the future.
![]()
## Navigating the Dashboard
Once your profile is set up, you'll be directed to the dashboard, serving as the central hub for all data and tools. The dashboard is segmented into various sections, each facilitating easy access to essential information. Take some time to acquaint yourself with the layout and navigation options to optimize your stockinsights.ai experience.
![]()
# Introduction
Source: https://docs.stockinsights.ai/introduction
stockinsights.ai, a Generative-AI enabled investment research platform
### Learn how stockinsights.ai can help you.
stockinsights.ai is a financial research tool that transforms how you work with unstructured public company data (like Annual Reports, Earnings Call Transcripts, etc.). Using Generative AI, it enables users to navigate and comprehend valuable fundamental data. With features powered by LLMs, it provides valuable insights for investment decisions at every stage of your journey: from discovering new opportunities to tracking your portfolio and conducting in-depth company research.
By streamlining analysis on qualitative data, it helps reduce your workload on manual data collation work and empower you to spend more time on making investment decisions. In addition to what you see on the website, it offers APIs that you can leverage to meet your unique needs. With stockinsights.ai, we hope you'll enjoy increased productivity, enhanced decision-making, and the flexibility to scale your investments with confidence.
Ask natural language queries & fetch vital data from filings.
Access concise readable summaries from long-formatted filings.
Get email alerts for the disclosures matching your criteria.
Check out our APIs that you can use for advanced needs.
# Claude Cowork Setup
Source: https://docs.stockinsights.ai/plugins/claude-cowork
Learn how to install and connect the stockinsights-in plugin on the Claude Cowork app to fetch Indian market data.
The **Claude Cowork** application supports plugins that allow you to use specialized skills and connectors directly in your workspace. This guide walks you through installing the **stockinsights-in** plugin to bring Indian equities research tools into your Claude Cowork workspace.
**Prerequisite**: Access to Claude Cowork plugins requires a paid Claude account (Pro, Team, or Enterprise plan).
***
## Step-by-Step Installation
Follow these steps to connect the `stockinsights-in` MCP server and authorize it with your stockinsights.ai account.
1. Click on the **Customize** button in the left navbar.
2. In the dialog box, go to the bottom and click on **Plugins**.
3. You will see a **+** (plus) icon there; click it to add a marketplace.
![Navigate to Add Marketplace]()
4. Select **Add from a repository** and enter the stockinsights plugins repository URL:
```text theme={null}
github.com/stockinsights-ai/plugins
```
5. Click **Add** to sync the marketplace.
![Add custom marketplace]()
1. Once the repository is synchronized, browse the list of available plugins in the newly added marketplace.
2. Locate **stockinsights-in**.
3. Click **Install** or select it to proceed.
![Install stockinsights-in plugin]()
1. Click on **Manage plugin** for the newly installed `stockinsights-in` plugin.
2. Select the **Connectors** tab (or navigate directly to **Customize** > **Connectors** in the sidebar).
1. Find the **stockinsights-in** MCP server in the list of connectors.
2. Click the **Connect** button next to it.
![Connect stockinsights-in connector]()
1. You will be redirected to the stockinsights.ai authentication portal.
2. **Log in** to your existing account, or **Sign up** if you don't have one yet.
3. Review the permissions requested by the Claude Cowork app.
4. Click **Authorize** to link your account.
![Authorize application connection]()
1. You will be redirected back to the Claude app.
2. Verify that the **stockinsights-in** MCP server connector status updates to **Connected** without any errors.
You're ready! Start a new chat or a Cowork task. You can trigger the plugin skills by typing `/` or clicking the `+` button in the chat box to select a skill, or simply ask Claude in plain text.
***
## Sample Queries to Try
Once connected, you can ask Claude questions about Indian companies, and it will automatically invoke the plugin tools behind the scenes to fetch accurate answers. Try these prompts:
```text 1. Filings Search theme={null}
"Find the latest corporate filings for Reliance Industries and list the main key sections."
```
```text 2. Earnings Call Analysis theme={null}
"Summarize the key growth outlook and capital expenditure comments from Tata Motors' last earnings transcript."
```
```text 3. Corporate Action Track theme={null}
"Check if there are any recent board meetings or announcements regarding dividend declarations for Infosys."
```
If you run into any issues during authorization, check that your browser is not blocking popups from `stockinsights.ai` or `claude.ai`.
# MCP & Plugins Overview
Source: https://docs.stockinsights.ai/plugins/overview
Integrate stockinsights.ai directly into your favorite AI assistants, chat interfaces, and IDEs using our Model Context Protocol (MCP) servers.
The **Model Context Protocol (MCP)** is an open standard that enables Large Language Models (LLMs) to securely connect to external data sources and developer tools.
By installing the **stockinsights.ai plugins or MCP servers**, you grant AI assistants like Claude, ChatGPT, and Cursor direct access to real-time company filings, corporate announcements, and AI-generated financial insights. You can query financial data directly in natural language without leaving your chat window.
***
## Available Servers & Plugins
We provide two distinct plugins optimized for different markets. You can connect either or both depending on your investment focus:
**India Equity Market**
Access BSE and NSE regulatory disclosures, corporate announcements, earnings call transcripts, financial statements (Income Statement, Balance Sheet, Cash Flow), and AI-generated insights.
**US Equity Market**
Access SEC filings (10-K, 10-Q, 8-K, 6-K), company profiles, earnings transcripts, and standardized financial statement data.
***
## Capabilities & Skills
Once connected, the stockinsights.ai plugins expose several **skills** (specialized tools) to your AI client:
* **Filings Search**: Search through thousands of reports and disclosures using keyword matching or semantic embeddings search.
* **AI Insights**: Generate concise summaries of dense documents, highlight risk factors, or extract key performance indicators.
* **Corporate Actions**: Fetch results calendars, board meetings, and track corporate announcements in real-time.
* **Financial Statements**: Retrieve structured balance sheets, income statements, and cash flows.
***
## Supported Clients
Our MCP servers and plugins are compatible with any client that supports the Model Context Protocol:
Configure stockinsights-in as a plug-and-play plugin inside Cowork.
Connect as a custom local or remote connector to use in your daily chats.
Query company filings directly from your editor workspace during analysis.
Add the stockinsights plugin to ChatGPT to chat with public company data.
Enhance web searches with direct company financial statements.
Interact with financial data from your command line.
**Looking for the setup guide?** Check out our step-by-step instructions to [install stockinsights-in on Claude Cowork](/plugins/claude-cowork).
# Embeddable AI Agent
Source: https://docs.stockinsights.ai/solutions/ai_agent
A New Way to Power Seamless, On-Demand Insights
## Overview
Imagine if every document you explore, every report you analyze, and every financial statement you encounter came with a knowledgeable assistant right by your side. This assistant can answer questions, retrieve information from specific sections, and even summarize complex details—all on demand. That’s precisely the power an Embeddable AI Agent brings to the table.
## What is an Embeddable AI Agent?
An embeddable AI agent is like a virtual research assistant you can integrate directly into your platform. Think of it as adding a well-trained assistant to your website or application, one that understands your data and can interact with users in real time, answering questions, offering insights, and even performing light analysis.
In stockinsights.ai, our AI Agent can be embedded within your own website or mobile app through a simple code snippet, allowing you to deliver sophisticated financial intelligence directly to your users in a familiar chat interface.
## Why Use an Embeddable AI Agent?
Embedding an AI agent brings unique advantages, allowing your users to interact with complex data in a natural, conversational way. Here’s why this matters:
1. On-Demand Information Access: Users no longer need to sift through lengthy documents to find specific answers. Instead, they can ask questions and get instant responses from the AI agent, which pulls data from relevant sections with pinpoint accuracy.
2. Enhanced User Engagement: Like a guide walking you through an unfamiliar city, the AI agent turns a static experience into an interactive one, making users more likely to stay engaged and return for further insights.
3. Customizable and Adaptable: Every business has unique needs, and our embeddable AI agent can be fine-tuned to understand and prioritize the aspects that matter most to your users, from specific datasets to preferred conversational styles.
## How Does it Work?
The beauty of the embeddable AI agent lies in its simplicity. Here’s a quick breakdown:
1. Step 1: Embed a code snippet into your web or mobile platform.
2. Step 2: Configure your AI agent using our documentation to ensure it’s optimized for your specific data needs and user expectations.
3. Step 3: Launch the agent, and instantly enable users to interact with your data through a chat interface tailored to your brand and functionality preferences.
Whether you need the agent to offer detailed answers from earnings reports or simplify summaries for complex disclosures, the AI agent becomes a bridge between users and data.
## Key Benefits of stockinsights.ai's AI Agent for Your Platform
1. Data Accuracy and Reliability: With advanced guard-railing, the AI agent can consistently draw accurate answers from your data, backed by our commitment to factual alignment and regular accuracy checks.
2. Scalability Across Markets: Our AI infrastructure is designed to scale, enabling you to deploy the agent across different markets with minimal setup and customization.
3. Versatile Applications: Whether integrated as a core part of your research workflow or as a feature to enhance user engagement on a financial website, the AI agent can adapt to various applications.
## Use Cases: How Financial Services and Research Firms Benefit
Financial institutions, research firms, and even family offices can leverage the embeddable AI agent for a range of practical use cases:
1. Investor Relations: Allow stakeholders to query filings, financial statements, or earnings reports directly from your platform.
2. User Engagement: Increase stickiness on your platform by enabling interactive data-driven conversations for retail investors.
3. Internal Research Assistance: Let analysts interact with in-depth data resources instantly, reducing time spent on document navigation and increasing focus on high-value analysis.
## Getting Started with the Embeddable AI Agent
Integrating our AI agent is straightforward, and our team is here to help with setup, customization, and ongoing support. For more technical details and to explore integration options, reach out to [founders@stockinsights.ai](mailto:founders@stockinsights.ai) with any questions. Together, we can help you bring a new level of insight and interactivity to your platform.
# Custom Prompts for Notifications
Source: https://docs.stockinsights.ai/solutions/custom-alerts
Personalize Your Notifications from Filings with Custom Prompts
## Overview
Enhance your research and monitoring capabilities with our "Custom Alerts" feature. Create and manage personalized notifications based on your specific prompts.
## User Story: Personalized Notifications
### The Challenge
An institutional investor needed efficient monitoring of portfolio developments without manual review of extensive filings. They sought automated notifications and summaries based on specific criteria.
### The Solution: Custom Alerts
We introduced "Custom Alerts," allowing investors to define criteria for tailored notifications and summaries.
### Key Capabilities
1. Define Criteria: Set alerts for specific events based on natural language prompts like "Notify when the CFO changes in any of my watchlist-A companies" or "Notify me when company-A makes any disclosure related to fund raise."
2. Receive Notifications: Instant email updates on defined triggers.
# Automated Company Screening
Source: https://docs.stockinsights.ai/solutions/screener
Screen Key Disclosures and Discover Investment Opportunities with Our Screener
## Overview
Discover how our custom "Screener" solution helped an institutional investor efficiently track key metrics and uncover investment opportunities through automated data extraction.
## User Story: Automated Order Book Tracking
### The Challenge
An institutional investor faced difficulties in efficiently tracking order books in a specific sector. The manual process of reviewing filings was time-consuming and prone to errors, often missing critical information. They needed an automated and reliable solution to stay ahead of market changes and make informed decisions quickly.
### The Solution: Screener
To address this challenge, we developed the "Screener," a custom solution leveraging generative AI (LLMs) to automatically extract and organize order book information from company filings.
### Key Capabilities of the Screener
1. Data Extraction: The Screener uses AI to extract detailed order book information from filings automatically.
2. Custom Filters: Investors can apply filters based on sector, market capitalization, and financial metrics to refine their searches.
3. Automated Updates: The Screener continuously monitors and updates order book data as new filings are released.
Screencer Opportunities: The capabilities of the Screener can be expanded to track other critical items, such as capacity expansions, revenue/profit guidance.
# Delivery & Retries
Source: https://docs.stockinsights.ai/webhooks/delivery-and-retries
How StockInsights delivers webhooks, which failures are retried, and on what schedule.
## What counts as success
StockInsights sends each event as an HTTPS `POST` and waits for your response.
* **`2xx`** — the delivery is considered successful.
* Anything else, a timeout, or a connection error — the delivery **failed** and
is handled per the [retry policy](#retries) below.
Respond `2xx` as soon as you have accepted the event. Acknowledge first, then do
any slow work asynchronously — a slow handler risks hitting the timeout and being
retried even though it succeeded.
Each request waits up to **10 seconds** for a response before it is treated as a
timeout and retried.
## Retries
When a delivery fails, StockInsights retries with exponential backoff and full
jitter — each retry is scheduled at a random point between zero and the backoff
for that attempt, which spreads retries out and avoids thundering herds.
A delivery is attempted up to **8 times** in total — the first attempt plus 7
retries — using this backoff schedule:
| After failed attempt | Wait before the next attempt (approx.) |
| -------------------- | -------------------------------------- |
| 1 | up to 1 minute |
| 2 | up to 5 minutes |
| 3 | up to 30 minutes |
| 4 | up to 2 hours |
| 5 | up to 6 hours |
| 6 | up to 12 hours |
| 7 | up to 24 hours |
After the 8th attempt fails, the delivery is marked failed and the event is not
sent again. In the worst case a delivery is retried for roughly two days before
it is given up on.
### Which failures are retried
| Response | Behavior |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `2xx` | Success — no retry. |
| `408`, `429`, or any `5xx` | Retried per the schedule above. |
| Timeout or connection error | Retried per the schedule above. |
| `3xx` | **Not retried.** Redirects are not followed. |
| Any other `4xx` (e.g. `400`, `401`, `404`) | **Not retried.** A `4xx` other than `408`/`429` signals the request will keep failing, so it is treated as a permanent failure. |
Because a non-`408`/`429` `4xx` is treated as permanent, make sure a failed
signature check or an unexpected payload does not cause your endpoint to return,
say, `400` or `404` for a request it should have accepted — that event is
dropped, not retried. If your endpoint is in a state where it *might* recover
(mid-deploy, secret not yet rolled out), return a `5xx` so the delivery is
retried. See [rotating the secret](/webhooks/verifying-signatures#rotating-the-secret).
Deliveries are also failed permanently, without retrying, when the destination
URL cannot be delivered to safely: a non-HTTPS scheme, a hostname that does not
resolve, or a hostname that resolves to a private or loopback address.
## Ordering and duplicates
* **Delivery is at-least-once.** Retries and network conditions mean the same
event can arrive more than once. Make your handler idempotent by de-duplicating
on the event `id` (the `evt_...` value).
* **Order is not guaranteed.** Events can arrive out of order, especially when
some were retried. Do not assume the order of receipt matches the order events
occurred; use `occurred_at` if ordering matters to you.
## Best practices
Return `2xx` immediately and process asynchronously to avoid timeouts.
De-duplicate on the event `id` so repeated deliveries are harmless.
Check the signature before acting on any payload.
Return `5xx` when you might recover, so the delivery is retried rather than dropped.
# Events & Payloads
Source: https://docs.stockinsights.ai/webhooks/events
The events you can subscribe to and the JSON payload StockInsights sends.
## Event envelope
Every webhook request has the same top-level shape. The specifics of the filing
live under `data`.
```json theme={null}
{
"id": "evt_0198c4a7-3f21-7d9e-b45c-6a1f2e3d4b5c",
"type": "filing.created",
"api_version": "v1",
"occurred_at": "2026-07-20T09:31:04.812431+00:00",
"data": {
"...": "event-specific, see below"
}
}
```
Unique event identifier: the literal prefix `evt_` followed by a UUID, so
40 characters in total. Use it to de-duplicate — the same event can be
delivered more than once. Store it as variable-length text rather than sizing
a column to today's value.
The event type. One of `filing.created` or `filing.enriched`. This is also sent
in the `X-StockInsights-Event` header.
The payload contract version. Currently `v1`. A breaking change to the payload
shape bumps this value.
When the event occurred, as an ISO 8601 timestamp in UTC. It includes
microseconds and a numeric `+00:00` offset — for example
`2026-07-20T09:31:04.812431+00:00`. Parse it with a real ISO 8601 parser
rather than matching a fixed layout or assuming a `Z` suffix.
The event-specific body. Its fields depend on `type` — see below.
## Event types vs. what you subscribe to
There are two event **types** on the wire — `filing.created` and
`filing.enriched` — but you subscribe at a finer grain. When configuring a
destination you pick from this catalog, and StockInsights only delivers the ones
you select. The **key** is the identifier shown next to each toggle in the
dashboard:
| Key | Subscription | Delivered as | How to recognize it |
| ---------------------------- | -------------------------- | ----------------- | ------------------------------------------ |
| `announcement.created` | Announcement created | `filing.created` | `data.document_type` is `announcement` |
| `announcement.summary_ready` | Announcement summary ready | `filing.enriched` | `data.enrichment_type` is `summary` |
| `quarterly-result.created` | Quarterly result created | `filing.created` | `data.document_type` is `quarterly-result` |
Because several subscriptions map onto the same wire `type`, always branch on
`data.document_type` (and `data.enrichment_type` for enriched events), not on
`type` alone.
## `filing.created`
Sent when a new filing is ingested — for example a new announcement or a newly
published quarterly result.
```json theme={null}
{
"id": "evt_0198c4a7-3f21-7d9e-b45c-6a1f2e3d4b5c",
"type": "filing.created",
"api_version": "v1",
"occurred_at": "2026-07-20T09:31:04.812431+00:00",
"data": {
"filing_id": "0198c4a5-9d3e-7f18-a2b6-3c4d5e6f7a8b",
"country": "IN",
"document_type": "announcement",
"company": {
"id": "RELIANCE",
"exchange": "NSE"
},
"published_date": "2026-07-20T09:30:00Z",
"source_url": "https://www.bseindia.com/...",
"url": "https://api.stockinsights.ai/v1/filings/0198c4a5-9d3e-7f18-a2b6-3c4d5e6f7a8b",
"period": {
"year": 2026,
"quarter": "Q1"
}
}
}
```
Identifier of the filing. Pass it to the filings API to fetch the full record.
Market the filing belongs to. Currently always `IN`.
The kind of filing, e.g. `announcement` or `quarterly-result`.
The company the filing belongs to.
Company identifier (ticker/symbol).
Exchange the company is listed on, e.g. `NSE` or `BSE`.
When the filing was published, as an ISO 8601 timestamp.
Link to the filing's original source document on the exchange or company site.
May be absent when no valid source link is available.
Canonical StockInsights API URL for the filing.
Reporting period, when applicable (e.g. for quarterly results). Contains `year`
(integer) and/or `quarter` (string, e.g. `"Q1"`), and is omitted entirely when
neither applies — as it is for most announcements.
## `filing.enriched`
Sent when an AI enrichment for a filing becomes available — for example an
announcement summary. Carries the same fields as `filing.created`, plus the
enrichment itself.
```json theme={null}
{
"id": "evt_0198c4a9-1b83-7c02-9e17-8d4a5f6b7c8e",
"type": "filing.enriched",
"api_version": "v1",
"occurred_at": "2026-07-20T09:33:12.406918+00:00",
"data": {
"filing_id": "0198c4a5-9d3e-7f18-a2b6-3c4d5e6f7a8b",
"country": "IN",
"document_type": "announcement",
"company": {
"id": "RELIANCE",
"exchange": "NSE"
},
"published_date": "2026-07-20T09:30:00Z",
"source_url": "https://www.bseindia.com/...",
"url": "https://api.stockinsights.ai/v1/filings/0198c4a5-9d3e-7f18-a2b6-3c4d5e6f7a8b",
"enrichment_type": "summary",
"enrichment": {
"summary": "The board approved a dividend of ...",
"category_id": 12,
"category": "Dividend",
"sub_category": "Interim dividend",
"sentiment": "positive",
"significance": true
}
}
}
```
The kind of enrichment. Currently always `summary`.
The enrichment content. Its shape depends on `enrichment_type`.
AI-generated summary of the announcement.
Announcement category name, e.g. `Dividend`. May be `null`.
Numeric id of the category. May be `null`.
Finer-grained classification within the category. May be `null`.
Sentiment read from the announcement, e.g. `positive`. May be `null`.
Whether the announcement is considered materially significant. May be `null`.
All other `data.*` fields match [`filing.created`](#filing-created).
# Webhooks Overview
Source: https://docs.stockinsights.ai/webhooks/overview
Receive filing events from StockInsights in real time, instead of polling the API.
## Overview
Webhooks push events to your server the moment they happen, so you don't have to
poll the API for new filings and enrichments. When a subscribed event occurs,
StockInsights sends a signed HTTPS `POST` request to the endpoint you configure.
Every request carries a JSON [event payload](/webhooks/events) and a
[signature](/webhooks/verifying-signatures) so you can confirm it
came from StockInsights and was not tampered with in transit.
Webhooks are available on API plans. Add a destination from **Account Settings →
Webhooks** in the dashboard.
## Adding a destination
1. Open **Account Settings → Webhooks** in the dashboard.
2. Enter your endpoint URL. It must be served over HTTPS — plain `http://` is
rejected.
3. Select the [events](/webhooks/events) you want delivered. A
destination with no events selected stays configured but receives nothing.
4. Save. Your **signing secret** is shown on the confirmation screen. You need it
to [verify signatures](/webhooks/verifying-signatures).
You can view and copy the signing secret again at any time from the Webhooks
section — reveal it with the eye icon on the destination card. There is no need
to rotate the secret just because you did not save it at creation.
You get **one webhook destination per account**, and it receives events for every
market you subscribe to. Today that is **India (`IN`)** only.
## Managing a destination
From the Webhooks section you can:
* **Edit the endpoint URL** or change which events are delivered.
* **Rotate the signing secret.** The previous secret stops verifying immediately,
so deploy the new secret to your endpoint before rotating, or right after.
* **Pause** the destination to stop delivery without deleting it, and **resume**
it later. A paused destination receives nothing.
* **Delete** the destination. This removes the endpoint and its secret, and you
stop receiving events immediately.
## Destination states
| State | Meaning |
| ---------- | --------------------------------------------------------- |
| **Active** | Delivering events normally. |
| **Paused** | You paused delivery. No events are sent until you resume. |
## Endpoint requirements
Your endpoint must:
* Accept `POST` requests over **HTTPS**. Plain `http://` is rejected.
* Be reachable at a **public** address. Endpoints that resolve to a private,
loopback, or otherwise non-public IP are rejected at delivery time, and the
event is not retried.
* Respond directly, without redirecting. Redirects are **not** followed — a `3xx`
is treated as a failed delivery.
Your endpoint should:
* [Verify the signature](/webhooks/verifying-signatures) on every
request before trusting the payload.
* Respond with a `2xx` status code as soon as it has accepted the event. Do the
heavy processing asynchronously — StockInsights
[retries](/webhooks/delivery-and-retries) on non-`2xx` responses
and times out slow endpoints.
* Be **idempotent**. Retries and at-least-once delivery mean the same event can
arrive more than once; de-duplicate on the event `id`.
## Next steps
The events you can subscribe to and the shape of each payload.
Confirm each request came from StockInsights.
Retry schedule, timeouts, and which failures are retried.
# Verifying Signatures
Source: https://docs.stockinsights.ai/webhooks/verifying-signatures
Confirm each webhook came from StockInsights and was not modified in transit.
## Why verify
Your webhook endpoint is a public URL, so anyone could `POST` to it. Every
StockInsights delivery is signed with a secret only you and StockInsights know.
Verifying the signature on each request proves it genuinely came from
StockInsights and that the body was not altered in transit.
Verify the signature before you trust or act on any webhook payload.
## Request headers
Each delivery includes these headers:
| Header | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-StockInsights-Signature` | The signature to verify, in the form `t=,v1=`. |
| `X-StockInsights-Event` | The event type, e.g. `filing.created`. |
| `X-StockInsights-Delivery` | Identifies one event going to one destination. Every retry of that delivery carries the **same** id, so it does not distinguish attempts. Useful in logs and support requests. |
| `User-Agent` | Always `stockinsights-webhooks/1.0`. |
## How the signature works
The `X-StockInsights-Signature` header has two comma-separated fields:
```
X-StockInsights-Signature: t=1721468400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8e6
```
* `t` — the UNIX timestamp (seconds) when the signature was generated.
* `v1` — a hex-encoded **HMAC-SHA256** of the string `{t}.{raw_body}`, keyed by
your signing secret.
The signed string is the timestamp, a literal `.`, then the **exact raw request
body**. To verify, recompute the HMAC and compare it to `v1` in constant time.
Your signing secret is **hex-encoded**. Decode it to raw bytes before using it
as the HMAC key. Compute the HMAC over the raw request body **exactly as
received** — do not parse and re-serialize the JSON first, or the bytes (and the
signature) will differ.
## Verify a signature
```javascript Node.js theme={null}
const crypto = require("crypto");
function verifyWebhook(rawBody, signatureHeader, secretHex, toleranceSeconds = 300) {
// Parse "t=...,v1=..."
const fields = {};
for (const part of signatureHeader.split(",")) {
const i = part.indexOf("=");
fields[part.slice(0, i)] = part.slice(i + 1);
}
const timestamp = Number(fields.t);
const provided = fields.v1;
if (!timestamp || !provided) return false;
// Reject stale timestamps to blunt replay attacks.
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
// The secret is hex-encoded; decode it to bytes for the HMAC key.
const key = Buffer.from(secretHex, "hex");
const expected = crypto
.createHmac("sha256", key)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(provided);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```
```python Python theme={null}
import hashlib
import hmac
import time
def verify_webhook(raw_body: bytes, signature_header: str, secret_hex: str, tolerance_seconds: int = 300) -> bool:
# Parse "t=...,v1=..."
try:
fields = dict(part.split("=", 1) for part in signature_header.split(","))
timestamp = int(fields["t"])
provided = fields["v1"]
except (KeyError, ValueError):
return False
# Reject stale timestamps to blunt replay attacks.
if abs(time.time() - timestamp) > tolerance_seconds:
return False
# The secret is hex-encoded; decode it to bytes for the HMAC key.
key = bytes.fromhex(secret_hex)
signed = f"{timestamp}.".encode() + raw_body # raw body, exactly as received
expected = hmac.new(key, signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, provided)
```
### Using it in a handler
```javascript Express theme={null}
const express = require("express");
const app = express();
// Capture the raw body — required for signature verification.
app.use("/webhooks/stockinsights", express.raw({ type: "application/json" }));
app.post("/webhooks/stockinsights", (req, res) => {
const signature = req.get("X-StockInsights-Signature");
const rawBody = req.body.toString("utf8");
// 503, not 400: a signature mismatch is usually a secret that has not rolled
// out yet, and only a 5xx gets retried. A 4xx drops the event permanently.
if (!verifyWebhook(rawBody, signature, process.env.STOCKINSIGHTS_WEBHOOK_SECRET)) {
return res.status(503).send("invalid signature");
}
const event = JSON.parse(rawBody);
// Acknowledge fast; process asynchronously.
res.sendStatus(200);
handleEvent(event); // your logic
});
```
```python Flask theme={null}
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/webhooks/stockinsights")
def stockinsights_webhook():
signature = request.headers.get("X-StockInsights-Signature", "")
raw_body = request.get_data() # bytes, exactly as received
# 503, not 400: a signature mismatch is usually a secret that has not rolled
# out yet, and only a 5xx gets retried. A 4xx drops the event permanently.
if not verify_webhook(raw_body, signature, WEBHOOK_SECRET):
abort(503, "invalid signature")
event = request.get_json()
# Acknowledge fast; process asynchronously.
handle_event(event) # your logic
return "", 200
```
## Timestamp tolerance and replay
The timestamp in `t` lets you reject old requests. StockInsights signs with the
current time, and the examples above reject anything more than **300 seconds**
(5 minutes) from your server's clock. This limits how long a captured request
could be replayed against your endpoint.
Keep your server clock in sync (NTP) so legitimate requests are not rejected for
clock drift. If your endpoint sits behind a proxy that buffers requests, make
sure the tolerance comfortably exceeds any added delay.
## Rotating the secret
Rotating the signing secret (from **Account Settings → Webhooks**) issues a new
secret and **invalidates the previous one immediately**. There is no overlap
window in which both secrets verify, so plan the swap:
1. Rotate in the dashboard and copy the new secret.
2. Deploy it to your endpoint promptly.
Between those two steps, deliveries are signed with the new secret while your
endpoint still holds the old one, so they will fail verification.
What happens to those deliveries depends entirely on the status code your
handler returns. A `5xx` (as in the examples above) is
[retried](/webhooks/delivery-and-retries), so the events land once
the new secret is deployed. A `4xx` is treated as a permanent failure and
**those events are dropped**. If your handler returns `400` or `401` on an
invalid signature, change it to a `5xx` before you rotate.
Rotation is only needed if the secret may have been exposed. You do not need to
rotate to recover a secret you did not save — it can be revealed again at any
time from the destination card in the dashboard.