Send one self-contained question in plain language. The AI Financial Research API resolves the entity, selects the required company-data tools and streams either a written answer with its underlying data or the raw tool results alone.
Built for server-side integration. Token authentication and product entitlement required.
POST /v2/ai/query
{
"query": "Find VICAT in FR and show
its financials",
"mode": "ai"
}
event: status
data: {"message":"Looking up company…"}
event: tool_call
data: {"tool":"get_company_by_identifiers"}
event: tool_result
data: {"tool":"…","data":{"id":101992009}}
event: text
data: {"content":"VICAT SA…"}
event: done
data: {"tools_used":["…"]}Illustrative event sequence · abridged
The AI API is for questions that do not map neatly to one preselected endpoint or one fixed response screen.
The service reads the question, resolves the company and decides which available company-data tools are needed to answer it.
Include the company and country in each request; the endpoint does not retain conversation history.Status, tool calls, tool results and answer fragments arrive over Server-Sent Events instead of appearing only after the full request completes.
A result is complete only when the stream reaches a done event.Use mode ai for a human-readable answer plus underlying results, or mode data when your application only needs the collected tool output.
Both modes use an SSE transport; data mode is not a single JSON response.The AI API is not a newer version of the deterministic API. They solve different engineering problems and can sit in the same architecture.
Your application chooses the financial endpoint and receives the structured records.
View the financial data APIThe service resolves the entity, selects the tools and streams the result.
View the AI research API| Decision | Deterministic Financial API | AI Financial Research API |
|---|---|---|
| Best starting point | Known company and known dataset | A self-contained business question |
| Execution | Your code calls one explicit endpoint | The service selects and can chain data tools |
| Transport | A structured JSON response | A live Server-Sent Events stream |
| Output | Financial fields, periods and ratios | ai: answer plus data · data: tool results only |
| Consistency | Fixed route and response contract; source records can update | Retrieved facts remain source-backed; tool path and prose can vary by question |
| Best workload | ETL, models, dashboards, scheduled retrieval | Research assistants, investigations, unfamiliar questions |
| Main trade-off | Your team defines the workflow and interpretation | More flexible input, but more streaming and review logic |
Simple rule: use deterministic endpoints for repeatable system workloads; use the AI API when a person or agent starts with a question whose retrieval path is not known in advance.
The API plans the retrieval, but your application still controls streaming, validation, persistence and how the result is presented.
Name the company, country and financial task in the query. Each call is stateless, so do not rely on a previous message to supply missing context.
Select ai when you need a ready-to-present explanation. Select data when you want the raw tool results and will create the calculations or user experience yourself.
Process complete SSE frames as they arrive: status, tool_call, tool_result, generating, text, suggested_actions and finally done.
Treat error events or a closed connection without done as incomplete. Store the relevant tool results, company identifiers and source metadata alongside any generated explanation.
Add a question box to a product so users can ask for company financials, trends or comparisons without choosing endpoints.
Best when the user starts with a question rather than a schema.Automate the first research pass across entity resolution and available financial records while keeping the retrieved data visible for review.
Best for guided investigation, not unattended final decisions.Route ambiguous companies or unfamiliar research requests to the AI layer while keeping routine ingestion on deterministic endpoints.
Best as a complement to a structured data pipeline.Keep routine ingestion, calculations and dashboards on deterministic endpoints. Use the AI Financial Research API for open-ended questions, ambiguous entities and requests that need several data tools. This protects schema control without forcing users to understand the endpoint catalogue.
See the deterministic data layerThe product choice affects transport, validation, cost controls and the evidence you need to retain.
Direct answers for product, data and engineering review.
It accepts a natural-language company research question, selects the available data tools needed for the task and streams the retrieved results. In ai mode it also streams a written answer; in data mode it returns the collected tool results without prose.
A standard deterministic API requires your application to know the endpoint and parameters in advance. The AI API starts from a question and plans which data tools to call. That makes it useful for open-ended research, but less suitable for fixed-schema bulk ingestion.
No. It is stateless. Send one self-contained question in each request and include the company, country and task needed to answer it.
ai mode streams a written answer plus the underlying tool data. data mode skips the prose and places the raw tool results in the final done event. Data mode still arrives as Server-Sent Events.
The service may need to resolve an entity and run several data operations before generating an answer. SSE lets your product show progress and process tool results as they arrive instead of waiting for one large final response.
The AI layer selects and orchestrates data tools. The financial records come from the underlying company-data services. Generated interpretation should remain separate from the retrieved values, and both should be retained when the answer needs to be reviewed.
Yes. Send mode data and read the data array in the terminal done event. This removes the written conclusion, but your client must still parse the SSE stream.
Use the deterministic financial API for routine workloads with known entities and fields. The AI API is a better fit for analyst questions, ambiguous inputs and multi-step research where the path is not known in advance.
Accept the result only after a done event. An error event, a failed tool result or a connection that closes before done must be handled explicitly rather than presented as a complete answer.
Keep the tool results, company identifiers, reporting periods, currency, account scope and returned source metadata beside the written explanation. Do not store only the prose if the result must later be audited or reproduced.
Tell us the companies, volume, output and usage rights your product requires.