{ "components": { "schemas": { "ActionMessage": { "description": "Notification that the agent is invoking a tool.", "properties": { "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "tool_arguments": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Arguments passed to the tool.", "title": "Tool Arguments" }, "tool_name": { "description": "Name of the tool being called.", "title": "Tool Name", "type": "string" }, "type": { "const": "ACTION", "default": "ACTION", "title": "Type", "type": "string" } }, "required": [ "tool_name" ], "title": "ActionMessage", "type": "object" }, "AnswerMessage": { "description": "A chunk of the agent's final answer text.", "properties": { "content": { "description": "Answer text content.", "title": "Content", "type": "string" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "ANSWER", "default": "ANSWER", "title": "Type", "type": "string" } }, "required": [ "content" ], "title": "AnswerMessage", "type": "object" }, "AuditMessage": { "description": "Detailed trace data from tool executions.", "properties": { "audit_traces": { "description": "Audit traces from tool executions.", "items": { "anyOf": [ { "$ref": "#/components/schemas/SearchAuditV1" }, { "$ref": "#/components/schemas/MarkdownAuditV1" }, { "$ref": "#/components/schemas/StructuredReportAuditV1" }, { "$ref": "#/components/schemas/SubAgentStartedAuditV1" }, { "$ref": "#/components/schemas/SubAgentCompletedAuditV1" } ] }, "title": "Audit Traces", "type": "array" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "AUDIT", "default": "AUDIT", "title": "Type", "type": "string" } }, "required": [ "audit_traces" ], "title": "AuditMessage", "type": "object" }, "AuditTraceBigdataResult": { "description": "Search results from the Bigdata content platform.", "properties": { "type": { "const": "CQS", "default": "CQS", "description": "Result type identifier.", "title": "Type", "type": "string" }, "values": { "description": "Matching documents.", "items": { "$ref": "#/components/schemas/BigdataDocument" }, "title": "Values", "type": "array" } }, "required": [ "values" ], "title": "AuditTraceBigdataResult", "type": "object" }, "AuditTraceExternalResult": { "description": "Search results from external web sources.", "properties": { "type": { "const": "EXTERNAL", "default": "EXTERNAL", "description": "Result type identifier.", "title": "Type", "type": "string" }, "values": { "description": "Matching external results.", "items": { "$ref": "#/components/schemas/ExternalResult" }, "title": "Values", "type": "array" } }, "required": [ "values" ], "title": "AuditTraceExternalResult", "type": "object" }, "BigdataChunk": { "description": "A text chunk from a Bigdata document.", "properties": { "bounding_boxes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/BoundingBox" }, "type": "array" }, { "type": "null" } ], "description": "Spatial positions for PDF-sourced content.", "title": "Bounding Boxes" }, "cnum": { "description": "Chunk number within the document.", "title": "Cnum", "type": "integer" }, "id": { "description": "Chunk identifier.", "title": "Id", "type": "string" }, "sentences": { "description": "Sentence positions within this chunk.", "items": { "$ref": "#/components/schemas/ChunkSentence" }, "title": "Sentences", "type": "array" }, "text": { "description": "Chunk text content.", "title": "Text", "type": "string" } }, "required": [ "id", "cnum", "text", "sentences" ], "title": "BigdataChunk", "type": "object" }, "BigdataDocument": { "description": "A document from the Bigdata content platform.", "properties": { "chunks": { "anyOf": [ { "items": { "$ref": "#/components/schemas/BigdataChunk" }, "type": "array" }, { "type": "null" } ], "description": "Text chunks with matched content.", "title": "Chunks" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Content type classification.", "title": "Content Type" }, "document_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope or section of the document.", "title": "Document Scope" }, "document_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Document type classification.", "title": "Document Type" }, "hd": { "description": "Document headline or title.", "title": "Hd", "type": "string" }, "id": { "description": "Unique document identifier.", "title": "Id", "type": "string" }, "language": { "description": "Document language code.", "title": "Language", "type": "string" }, "rp_provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provider identifier.", "title": "Rp Provider Id" }, "source_rank": { "description": "Ranking weight of the source.", "title": "Source Rank", "type": "integer" }, "src_key": { "description": "Source key identifier.", "title": "Src Key", "type": "string" }, "src_name": { "description": "Source display name.", "title": "Src Name", "type": "string" }, "ts": { "description": "Publication timestamp.", "title": "Ts", "type": "string" }, "type": { "const": "BIGDATA", "default": "BIGDATA", "description": "Source type identifier.", "title": "Type", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the original document.", "title": "Url" } }, "required": [ "hd", "id", "language", "src_key", "src_name", "source_rank", "ts" ], "title": "BigdataDocument", "type": "object" }, "BoundingBox": { "description": "Spatial coordinates of content on a document page.", "properties": { "bottom": { "title": "Bottom", "type": "number" }, "left": { "title": "Left", "type": "number" }, "page": { "title": "Page", "type": "integer" }, "right": { "title": "Right", "type": "number" }, "top": { "title": "Top", "type": "number" } }, "required": [ "bottom", "left", "page", "right", "top" ], "title": "BoundingBox", "type": "object" }, "ChartMessage": { "description": "A chart the agent produced while running code.", "properties": { "caption": { "description": "Short description of the chart.", "title": "Caption", "type": "string" }, "chart_id": { "description": "Unique identifier for the chart.", "title": "Chart Id", "type": "string" }, "chart_type": { "description": "Chart shape, e.g. 'bar', 'line', 'scatter', 'area', or 'histogram'.", "title": "Chart Type", "type": "string" }, "data_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of data points plotted in the chart.", "title": "Data Points" }, "end": { "description": "End offset in the cumulative answer text (exclusive).", "title": "End", "type": "integer" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "start": { "description": "Start offset in the cumulative answer text.", "title": "Start", "type": "integer" }, "title": { "description": "Chart title.", "title": "Title", "type": "string" }, "type": { "const": "CHART", "default": "CHART", "title": "Type", "type": "string" }, "vega_lite_spec": { "additionalProperties": true, "description": "A standard Vega-Lite specification for the chart. Render it with any Vega-Lite renderer: https://vega.github.io/vega-lite/docs/", "title": "Vega Lite Spec", "type": "object" } }, "required": [ "chart_id", "title", "caption", "chart_type", "vega_lite_spec", "start", "end" ], "title": "ChartMessage", "type": "object" }, "ChunkSentence": { "description": "Position reference within a document chunk.", "properties": { "pnum": { "description": "Paragraph number.", "title": "Pnum", "type": "integer" }, "snum": { "description": "Sentence number within the paragraph.", "title": "Snum", "type": "integer" } }, "required": [ "pnum", "snum" ], "title": "ChunkSentence", "type": "object" }, "CompleteMessage": { "description": "Signals that the agent has finished processing the request.", "properties": { "checkpoint_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Checkpoint for continuing this conversation.", "title": "Checkpoint Id" }, "consumption": { "description": "Resource usage breakdown for this request.", "items": { "discriminator": { "mapping": { "base": "#/components/schemas/TokenTierConsumption", "pro": "#/components/schemas/TokenTierConsumption", "search": "#/components/schemas/SearchConsumption", "search_endpoint": "#/components/schemas/SearchEndpointConsumption", "structured_data": "#/components/schemas/StructuredDataConsumption" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/TokenTierConsumption" }, { "$ref": "#/components/schemas/SearchConsumption" }, { "$ref": "#/components/schemas/StructuredDataConsumption" }, { "$ref": "#/components/schemas/SearchEndpointConsumption" } ] }, "title": "Consumption", "type": "array" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "COMPLETE", "default": "COMPLETE", "title": "Type", "type": "string" } }, "required": [ "consumption" ], "title": "CompleteMessage", "type": "object" }, "ComponentType": { "description": "Types of structured report components.", "enum": [ "company_overview", "key_financial_highlights", "analyst_data", "forward_estimates", "price_performance", "latest_earnings", "financial_data", "additional_financial_metrics", "revenue_segmentation", "earnings_calendar" ], "title": "ComponentType", "type": "string" }, "ContentFilter": { "description": "Composable content filter using logical operators.", "properties": { "all_of": { "description": "Match content satisfying all of these filters.", "items": { "discriminator": { "mapping": { "DOCUMENT_ID": "#/components/schemas/DocumentIdFilter", "SOURCE_TYPE": "#/components/schemas/SourceFilter" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/DocumentIdFilter" }, { "$ref": "#/components/schemas/SourceFilter" } ] }, "title": "All Of", "type": "array" }, "any_of": { "description": "Match content satisfying at least one of these filters.", "items": { "discriminator": { "mapping": { "DOCUMENT_ID": "#/components/schemas/DocumentIdFilter", "SOURCE_TYPE": "#/components/schemas/SourceFilter" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/DocumentIdFilter" }, { "$ref": "#/components/schemas/SourceFilter" } ] }, "title": "Any Of", "type": "array" }, "none_of": { "description": "Exclude content matching any of these filters.", "items": { "discriminator": { "mapping": { "DOCUMENT_ID": "#/components/schemas/DocumentIdFilter", "SOURCE_TYPE": "#/components/schemas/SourceFilter" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/DocumentIdFilter" }, { "$ref": "#/components/schemas/SourceFilter" } ] }, "title": "None Of", "type": "array" } }, "title": "ContentFilter", "type": "object" }, "DataTable": { "description": "A table of structured data.", "properties": { "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional table description.", "title": "Caption" }, "headers": { "description": "Column header names.", "items": { "type": "string" }, "minItems": 1, "title": "Headers", "type": "array" }, "rows": { "description": "Row data as key-value mappings.", "items": { "additionalProperties": true, "type": "object" }, "title": "Rows", "type": "array" } }, "required": [ "headers" ], "title": "DataTable", "type": "object" }, "DateRange": { "description": "Absolute time range for filtering content.", "properties": { "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "End of the time range (ISO 8601 UTC, e.g. '2024-12-31T23:59:59Z').", "title": "End" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Start of the time range (ISO 8601 UTC, e.g. '2024-01-01T00:00:00Z').", "title": "Start" } }, "title": "DateRange", "type": "object" }, "DocumentIdFilter": { "description": "Filter by specific document identifiers.", "properties": { "document_ids": { "description": "Set of document IDs to match.", "items": { "type": "string" }, "maxItems": 1000, "minItems": 1, "title": "Document Ids", "type": "array", "uniqueItems": true }, "type": { "const": "DOCUMENT_ID", "description": "Filter type identifier.", "title": "Type", "type": "string" } }, "required": [ "type", "document_ids" ], "title": "DocumentIdFilter", "type": "object" }, "EntityFilter": { "description": "Filter content by entity identifiers using logical operators.", "properties": { "all_of": { "description": "Match content mentioning all of these entity IDs.", "items": { "type": "string" }, "title": "All Of", "type": "array" }, "any_of": { "description": "Match content mentioning any of these entity IDs.", "items": { "type": "string" }, "title": "Any Of", "type": "array" }, "none_of": { "description": "Exclude content mentioning any of these entity IDs.", "items": { "type": "string" }, "title": "None Of", "type": "array" } }, "title": "EntityFilter", "type": "object" }, "ErrorMessage": { "description": "An unrecoverable error during processing.", "properties": { "error": { "description": "Error description.", "title": "Error", "type": "string" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "ERROR", "default": "ERROR", "title": "Type", "type": "string" } }, "required": [ "error" ], "title": "ErrorMessage", "type": "object" }, "ExternalResult": { "description": "A result from an external web source.", "properties": { "action": { "$ref": "#/components/schemas/ExternalSourceAction", "description": "Source metadata and URL." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brief summary.", "title": "Description" }, "hd": { "description": "Headline or title.", "title": "Hd", "type": "string" }, "id": { "description": "Unique identifier for this result.", "title": "Id", "type": "string" }, "text": { "description": "Content text excerpt.", "title": "Text", "type": "string" }, "ts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication timestamp.", "title": "Ts" }, "type": { "const": "EXTERNAL", "default": "EXTERNAL", "description": "Source type identifier.", "title": "Type", "type": "string" } }, "required": [ "id", "hd", "text", "action" ], "title": "ExternalResult", "type": "object" }, "ExternalSourceAction": { "description": "Metadata for an external web source.", "properties": { "favicon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the source's favicon.", "title": "Favicon Url" }, "hd": { "description": "Headline or title.", "title": "Hd", "type": "string" }, "name": { "description": "Display name of the source.", "title": "Name", "type": "string" }, "type": { "const": "EXTERNAL", "default": "EXTERNAL", "description": "Source type identifier.", "title": "Type", "type": "string" }, "url": { "description": "URL of the original content.", "title": "Url", "type": "string" } }, "required": [ "name", "hd", "url" ], "title": "ExternalSourceAction", "type": "object" }, "GroundingMessage": { "description": "Citations linking answer text spans to their sources.", "properties": { "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "references": { "description": "Source references for spans of the answer text.", "items": { "$ref": "#/components/schemas/GroundingReference" }, "title": "References", "type": "array" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "GROUNDING", "default": "GROUNDING", "title": "Type", "type": "string" } }, "required": [ "references" ], "title": "GroundingMessage", "type": "object" }, "GroundingReference": { "description": "A citation linking a span of answer text to its source.", "properties": { "audit_id": { "description": "Identifier linking this reference to its audit trace.", "title": "Audit Id", "type": "string" }, "end": { "description": "End character offset (exclusive) in the answer text.", "title": "End", "type": "integer" }, "source": { "anyOf": [ { "discriminator": { "mapping": { "BIGDATA": "#/components/schemas/BigdataDocument", "EXTERNAL": "#/components/schemas/ExternalResult" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ExternalResult" }, { "$ref": "#/components/schemas/BigdataDocument" } ] }, { "type": "null" } ], "description": "The referenced source document or web result.", "title": "Source" }, "start": { "description": "Start character offset in the answer text.", "title": "Start", "type": "integer" }, "tool_name": { "description": "Name of the tool that produced this reference.", "title": "Tool Name", "type": "string" } }, "required": [ "start", "end", "tool_name", "audit_id" ], "title": "GroundingReference", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "HeaderBlock": { "description": "A heading block within a report section.", "properties": { "block_type": { "const": "header", "default": "header", "description": "Block type identifier.", "title": "Block Type", "type": "string" }, "level": { "default": 2, "description": "Heading level (1-6).", "maximum": 6.0, "minimum": 1.0, "title": "Level", "type": "integer" }, "text": { "description": "Heading text.", "minLength": 1, "title": "Text", "type": "string" } }, "required": [ "text" ], "title": "HeaderBlock", "type": "object" }, "LlmRetryMessage": { "description": "Notification that the agent is retrying a failed operation.", "properties": { "message": { "description": "Human-readable retry status.", "title": "Message", "type": "string" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "LLM_RETRY", "default": "LLM_RETRY", "title": "Type", "type": "string" } }, "required": [ "message" ], "title": "LlmRetryMessage", "type": "object" }, "MarkdownAuditV1": { "description": "Audit trace for generated markdown content.", "properties": { "audit_type": { "const": "MarkdownAuditV1", "default": "MarkdownAuditV1", "title": "Audit Type", "type": "string" }, "content": { "description": "The generated markdown content.", "title": "Content", "type": "string" }, "title": { "description": "Title of the generated content.", "title": "Title", "type": "string" }, "tool_id": { "description": "Identifier of the tool that produced this trace.", "title": "Tool Id", "type": "string" } }, "required": [ "tool_id", "title", "content" ], "title": "MarkdownAuditV1", "type": "object" }, "ModelName": { "description": "Available models for execution.", "enum": [ "base", "pro" ], "title": "ModelName", "type": "string" }, "PersistenceMode": { "description": "Controls whether conversation history is saved.", "enum": [ "enabled", "disabled" ], "title": "PersistenceMode", "type": "string" }, "Plan": { "description": "A structured research plan with ordered steps.", "properties": { "steps": { "default": [], "description": "Ordered list of research steps.", "items": { "$ref": "#/components/schemas/Step" }, "title": "Steps", "type": "array" }, "title": { "description": "Short title summarizing the research objective.", "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "Plan", "type": "object" }, "PlanningMessage": { "description": "Updates to the agent's research plan.", "properties": { "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "plan": { "$ref": "#/components/schemas/Plan", "description": "Current state of the research plan." }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "PLANNING", "default": "PLANNING", "title": "Type", "type": "string" } }, "required": [ "plan" ], "title": "PlanningMessage", "type": "object" }, "PythonCodeExecutionToolConfig": { "description": "Configuration for the Python code execution tool.\n\nThe agent can run sandboxed Python (pandas, numpy, scipy, statsmodels,\nscikit-learn, duckdb, plus Bigdata data and chart helpers) to analyze\ndata and, when chart generation is enabled, render interactive charts\ninline in the response.", "properties": { "chart_generation_enabled": { "default": false, "description": "Allow the agent to render interactive charts (scatter, line, bar, area, histogram). Charts come back as separate streaming events alongside the answer; clients render them with their preferred Vega-Lite renderer. Defaults to off \u2014 opt in explicitly when your client can render the chart events.", "title": "Chart Generation Enabled", "type": "boolean" }, "enabled": { "default": true, "description": "Whether the agent may run Python code for this request.", "title": "Enabled", "type": "boolean" } }, "title": "PythonCodeExecutionToolConfig", "type": "object" }, "QueryFilters": { "description": "Filters applied to search queries to narrow results.", "properties": { "content": { "anyOf": [ { "$ref": "#/components/schemas/ContentFilter" }, { "type": "null" } ], "description": "Filter by content source or document identifiers." }, "entities": { "anyOf": [ { "$ref": "#/components/schemas/EntityFilter" }, { "type": "null" } ], "description": "Filter by entity identifiers." }, "period": { "anyOf": [ { "$ref": "#/components/schemas/DateRange" }, { "type": "null" } ], "description": "Restrict results to a specific time range." }, "tags": { "description": "Tags to filter on.", "items": { "type": "string" }, "maxItems": 1000, "title": "Tags", "type": "array", "uniqueItems": true } }, "title": "QueryFilters", "type": "object" }, "RankingParameters": { "description": "Parameters that influence how search results are ranked.", "properties": { "freshness_boost": { "anyOf": [ { "maximum": 10.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Prioritize more recent content (1-10).", "title": "Freshness Boost" }, "source_boost": { "anyOf": [ { "maximum": 10.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Boost results from high-quality, authoritative sources (1-10).", "title": "Source Boost" } }, "title": "RankingParameters", "type": "object" }, "ReportComponent": { "description": "A section of a structured report.", "properties": { "blocks": { "description": "Content blocks within this section.", "items": { "anyOf": [ { "$ref": "#/components/schemas/HeaderBlock" }, { "$ref": "#/components/schemas/TextBlock" }, { "$ref": "#/components/schemas/StructuredBlock" } ] }, "title": "Blocks", "type": "array" }, "component_type": { "$ref": "#/components/schemas/ComponentType", "description": "Type of report section." }, "title": { "description": "Section title.", "title": "Title", "type": "string" } }, "required": [ "component_type", "title" ], "title": "ReportComponent", "type": "object" }, "ResearchAgentRequest": { "description": "Request to execute a research query.", "properties": { "chat_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provide a previous chat ID to continue a conversation.", "title": "Chat Id" }, "expected_output": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Optional guidance for the final answer's tone, structure, and format.", "title": "Expected Output" }, "from_checkpoint_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resume or edit a conversation from a specific checkpoint.", "title": "From Checkpoint Id" }, "message": { "description": "Your research question or request.", "minLength": 1, "title": "Message", "type": "string" }, "model_name": { "$ref": "#/components/schemas/ModelName", "default": "base", "description": "Selects the model capability tier. Use \"base\" for the default routing strategy, or \"pro\" to allow the most capable available model when higher reasoning or accuracy is required. Model selection is dynamic and may vary based on task type, availability, and failover." }, "persistence_mode": { "$ref": "#/components/schemas/PersistenceMode", "default": "disabled", "description": "Set to 'enabled' to save conversation history for follow-up questions." }, "research_effort": { "$ref": "#/components/schemas/ResearchEffort", "description": "Controls research depth. Use 'lite' for quick answers or 'standard' for thorough analysis." }, "structured_output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "JSON Schema for structured data extraction from the research results.", "title": "Structured Output Schema" }, "tools_configs": { "anyOf": [ { "$ref": "#/components/schemas/ToolsConfigs" }, { "type": "null" } ], "description": "Per-tool configuration overrides. Set only the tools you want to customize; omitted tools use the server-side default." } }, "required": [ "research_effort", "message" ], "title": "ResearchAgentRequest", "type": "object" }, "ResearchAgentResponse": { "description": "A single streaming event from the Research Agent.", "properties": { "chat_id": { "description": "Identifier for this conversation.", "title": "Chat Id", "type": "string" }, "message": { "description": "The streamed message event.", "discriminator": { "mapping": { "ACTION": "#/components/schemas/ActionMessage", "ANSWER": "#/components/schemas/AnswerMessage", "AUDIT": "#/components/schemas/AuditMessage", "CHART": "#/components/schemas/ChartMessage", "COMPLETE": "#/components/schemas/CompleteMessage", "ERROR": "#/components/schemas/ErrorMessage", "GROUNDING": "#/components/schemas/GroundingMessage", "LLM_RETRY": "#/components/schemas/LlmRetryMessage", "PLANNING": "#/components/schemas/PlanningMessage", "STRUCTURED_OUTPUT": "#/components/schemas/StructuredOutputMessage", "THINKING": "#/components/schemas/ThinkingMessage", "TOOL_ERROR": "#/components/schemas/ToolErrorMessage" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ThinkingMessage" }, { "$ref": "#/components/schemas/ActionMessage" }, { "$ref": "#/components/schemas/AnswerMessage" }, { "$ref": "#/components/schemas/CompleteMessage" }, { "$ref": "#/components/schemas/ErrorMessage" }, { "$ref": "#/components/schemas/AuditMessage" }, { "$ref": "#/components/schemas/GroundingMessage" }, { "$ref": "#/components/schemas/ChartMessage" }, { "$ref": "#/components/schemas/ToolErrorMessage" }, { "$ref": "#/components/schemas/PlanningMessage" }, { "$ref": "#/components/schemas/LlmRetryMessage" }, { "$ref": "#/components/schemas/StructuredOutputMessage" } ], "title": "Message" } }, "required": [ "chat_id", "message" ], "title": "ResearchAgentResponse", "type": "object" }, "ResearchEffort": { "description": "Controls the depth and thoroughness of the research.", "enum": [ "lite", "standard" ], "title": "ResearchEffort", "type": "string" }, "SearchAuditV1": { "description": "Audit trace for a search operation.", "properties": { "audit_type": { "const": "SearchAuditV1", "default": "SearchAuditV1", "title": "Audit Type", "type": "string" }, "query": { "$ref": "#/components/schemas/TraceQuery", "description": "The query that was executed." }, "results": { "description": "Search results grouped by source type.", "items": { "anyOf": [ { "$ref": "#/components/schemas/AuditTraceBigdataResult" }, { "$ref": "#/components/schemas/AuditTraceExternalResult" } ] }, "title": "Results", "type": "array" }, "tool_id": { "description": "Identifier of the tool that produced this trace.", "title": "Tool Id", "type": "string" } }, "required": [ "tool_id", "query", "results" ], "title": "SearchAuditV1", "type": "object" }, "SearchConsumption": { "description": "Search tokens consumed against a content tier.", "properties": { "content_tier": { "description": "Content tier the search ran against.", "title": "Content Tier", "type": "string" }, "mode": { "const": "fast", "default": "fast", "description": "Search mode the tokens were consumed in.", "title": "Mode", "type": "string" }, "tokens_count": { "description": "Number of search tokens consumed.", "title": "Tokens Count", "type": "integer" }, "type": { "const": "search", "default": "search", "title": "Type", "type": "string" } }, "required": [ "content_tier", "tokens_count" ], "title": "SearchConsumption", "type": "object" }, "SearchEndpointConsumption": { "description": "Search tokens consumed against a specific search endpoint.", "properties": { "endpoint": { "description": "Search endpoint the tokens were consumed against.", "enum": [ "comentions", "volume", "knowledge-graph" ], "title": "Endpoint", "type": "string" }, "tokens_count": { "description": "Number of search tokens consumed.", "title": "Tokens Count", "type": "integer" }, "type": { "const": "search_endpoint", "default": "search_endpoint", "title": "Type", "type": "string" } }, "required": [ "endpoint", "tokens_count" ], "title": "SearchEndpointConsumption", "type": "object" }, "SearchToolConfig": { "description": "Configuration for the search tool.", "properties": { "query_filters": { "anyOf": [ { "$ref": "#/components/schemas/QueryFilters" }, { "type": "null" } ], "description": "Filters to apply to search queries." }, "ranking_parameters": { "anyOf": [ { "$ref": "#/components/schemas/RankingParameters" }, { "type": "null" } ], "description": "Parameters to influence result ranking." } }, "title": "SearchToolConfig", "type": "object" }, "SourceFilter": { "description": "Filter by content source identifiers.", "properties": { "sources_ids": { "description": "Set of source IDs to match.", "items": { "type": "string" }, "maxItems": 1000, "minItems": 1, "title": "Sources Ids", "type": "array", "uniqueItems": true }, "type": { "const": "SOURCE_TYPE", "description": "Filter type identifier.", "title": "Type", "type": "string" } }, "required": [ "type", "sources_ids" ], "title": "SourceFilter", "type": "object" }, "Step": { "description": "A single step within a research plan.", "properties": { "description": { "description": "What this step will investigate or produce.", "title": "Description", "type": "string" }, "status": { "$ref": "#/components/schemas/StepStatus", "default": "NOT_STARTED", "description": "Current status of this step." } }, "required": [ "description" ], "title": "Step", "type": "object" }, "StepStatus": { "description": "Status of a research plan step.", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "SKIPPED", "FAILED" ], "title": "StepStatus", "type": "string" }, "StructuredBlock": { "description": "A structured data block (e.g., table) within a report section.", "properties": { "block_type": { "const": "structured", "default": "structured", "description": "Block type identifier.", "title": "Block Type", "type": "string" }, "structured_type": { "$ref": "#/components/schemas/StructuredType", "default": "table", "description": "Type of structured data." }, "table": { "$ref": "#/components/schemas/DataTable", "description": "Table data." } }, "required": [ "table" ], "title": "StructuredBlock", "type": "object" }, "StructuredDataConsumption": { "description": "Structured-data tokens consumed against a content tier.", "properties": { "content_tier": { "description": "Content tier the structured-data read ran against.", "title": "Content Tier", "type": "string" }, "tokens_count": { "description": "Number of structured-data tokens consumed.", "title": "Tokens Count", "type": "integer" }, "type": { "const": "structured_data", "default": "structured_data", "title": "Type", "type": "string" } }, "required": [ "content_tier", "tokens_count" ], "title": "StructuredDataConsumption", "type": "object" }, "StructuredOutputMessage": { "description": "Structured data extracted from the research results.", "properties": { "content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" } ], "description": "Extracted structured data matching the requested schema.", "title": "Content" }, "json_schema": { "additionalProperties": true, "description": "The JSON Schema used to produce this output.", "title": "Json Schema", "type": "object" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "STRUCTURED_OUTPUT", "default": "STRUCTURED_OUTPUT", "title": "Type", "type": "string" } }, "required": [ "json_schema", "content" ], "title": "StructuredOutputMessage", "type": "object" }, "StructuredReport": { "description": "A structured report with multiple sections.", "properties": { "components": { "description": "Report sections.", "items": { "$ref": "#/components/schemas/ReportComponent" }, "title": "Components", "type": "array" }, "title": { "description": "Report title.", "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "StructuredReport", "type": "object" }, "StructuredReportAuditV1": { "description": "Audit trace for a structured data report.", "properties": { "audit_type": { "const": "StructuredReportAuditV1", "default": "StructuredReportAuditV1", "title": "Audit Type", "type": "string" }, "structured_report": { "$ref": "#/components/schemas/StructuredReport", "description": "The generated structured report." }, "tool_id": { "description": "Identifier of the tool that produced this trace.", "title": "Tool Id", "type": "string" } }, "required": [ "tool_id", "structured_report" ], "title": "StructuredReportAuditV1", "type": "object" }, "StructuredType": { "description": "Types of structured data blocks.", "enum": [ "table" ], "title": "StructuredType", "type": "string" }, "SubAgentCompletedAuditV1": { "description": "Audit trace emitted when a sub-agent finishes its research task.", "properties": { "audit_type": { "const": "SubAgentCompletedAuditV1", "default": "SubAgentCompletedAuditV1", "title": "Audit Type", "type": "string" }, "consumption": { "description": "Resource usage for this sub-agent's execution.", "items": { "discriminator": { "mapping": { "base": "#/components/schemas/TokenTierConsumption", "pro": "#/components/schemas/TokenTierConsumption", "search": "#/components/schemas/SearchConsumption", "search_endpoint": "#/components/schemas/SearchEndpointConsumption", "structured_data": "#/components/schemas/StructuredDataConsumption" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/TokenTierConsumption" }, { "$ref": "#/components/schemas/SearchConsumption" }, { "$ref": "#/components/schemas/StructuredDataConsumption" }, { "$ref": "#/components/schemas/SearchEndpointConsumption" } ] }, "title": "Consumption", "type": "array" }, "success": { "description": "Whether the sub-agent completed successfully.", "title": "Success", "type": "boolean" }, "tool_id": { "description": "Identifier of the tool that produced this trace.", "title": "Tool Id", "type": "string" } }, "required": [ "tool_id", "success" ], "title": "SubAgentCompletedAuditV1", "type": "object" }, "SubAgentStartedAuditV1": { "description": "Audit trace emitted when a sub-agent begins its research task.", "properties": { "agent_role": { "description": "Role name of the sub-agent.", "title": "Agent Role", "type": "string" }, "audit_type": { "const": "SubAgentStartedAuditV1", "default": "SubAgentStartedAuditV1", "title": "Audit Type", "type": "string" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/Plan" }, { "type": "null" } ], "description": "The sub-agent's research plan, if available." }, "plan_title": { "description": "Title of the sub-agent's research plan.", "title": "Plan Title", "type": "string" }, "step_index": { "description": "Index of the plan step this sub-agent is executing.", "title": "Step Index", "type": "integer" }, "tool_id": { "description": "Identifier of the tool that produced this trace.", "title": "Tool Id", "type": "string" } }, "required": [ "tool_id", "agent_role", "plan_title", "step_index" ], "title": "SubAgentStartedAuditV1", "type": "object" }, "TextBlock": { "description": "A plain text block within a report section.", "properties": { "block_type": { "const": "text", "default": "text", "description": "Block type identifier.", "title": "Block Type", "type": "string" }, "content": { "description": "Text content.", "title": "Content", "type": "string" } }, "required": [ "content" ], "title": "TextBlock", "type": "object" }, "ThinkingMessage": { "description": "The agent's intermediate reasoning while researching.", "properties": { "content": { "description": "The agent's reasoning text.", "title": "Content", "type": "string" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "type": { "const": "THINKING", "default": "THINKING", "title": "Type", "type": "string" } }, "required": [ "content" ], "title": "ThinkingMessage", "type": "object" }, "TokenTierConsumption": { "description": "Token usage for a specific model tier.", "properties": { "cached_tokens": { "default": 0, "description": "Number of tokens served from cache.", "title": "Cached Tokens", "type": "integer" }, "input_tokens": { "description": "Number of input tokens consumed.", "title": "Input Tokens", "type": "integer" }, "output_tokens": { "description": "Number of output tokens generated.", "title": "Output Tokens", "type": "integer" }, "type": { "description": "Model tier this consumption applies to.", "enum": [ "base", "pro" ], "title": "Type", "type": "string" } }, "required": [ "type", "input_tokens", "output_tokens" ], "title": "TokenTierConsumption", "type": "object" }, "ToolDescriptor": { "description": "Per-tool entry returned by `GET /v1/tools`.\n\nThe tool catalog is dynamic \u2014 first-party tools plus any MCP-backed\ntools surfaced through connectors the requesting user has connected.\nUse this endpoint at runtime to discover which tool ids are available\nand what each tool's `tools_configs` entry should look like.", "properties": { "config_schema": { "additionalProperties": true, "description": "JSON Schema for this tool's per-request configuration. Use this to validate or render UI for the value of `tools_configs[]` before submitting a request.", "title": "Config Schema", "type": "object" }, "default": { "additionalProperties": true, "description": "Default configuration the server applies for this tool when the caller does not specify one in `tools_configs`.", "title": "Default", "type": "object" }, "description": { "description": "Tool description as the agent sees it, useful for knowing when the tool will be selected.", "title": "Description", "type": "string" }, "id": { "description": "Tool identifier. Use this string as the key in `tools_configs` when calling the research agent. MCP-backed tools use the `__` namespace convention.", "title": "Id", "type": "string" }, "name": { "description": "Human-readable tool name.", "title": "Name", "type": "string" }, "source": { "description": "`bigdata` for first-party tools provided by the Bigdata Research Agent; `mcp` for tools surfaced through a connected MCP provider.", "enum": [ "bigdata", "mcp" ], "title": "Source", "type": "string" } }, "required": [ "id", "name", "description", "config_schema", "default", "source" ], "title": "ToolDescriptor", "type": "object" }, "ToolErrorMessage": { "description": "A recoverable error from a specific tool.", "properties": { "error": { "description": "Error description.", "title": "Error", "type": "string" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Groups related message chunks that belong to the same logical unit.", "title": "Message Id" }, "role": { "default": "assistant", "description": "Message source: 'assistant' for the main agent, or a sub-agent role name.", "title": "Role", "type": "string" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the tool that encountered the error.", "title": "Tool Name" }, "type": { "const": "TOOL_ERROR", "default": "TOOL_ERROR", "title": "Type", "type": "string" } }, "required": [ "error" ], "title": "ToolErrorMessage", "type": "object" }, "ToolsConfigs": { "additionalProperties": { "description": "MCP-backed tool config keyed by `__`. Discover keys via `GET /v1/tools`.", "type": "object" }, "description": "Per-tool configuration overrides for a single request.\n\nThe named fields below (`search`, `python_code_execution`) document the\nfirst-party tools with rich per-tool config. The model also accepts\nadditional keys for MCP-backed connector tools \u2014 keyed by the\n`__` id discovered via `GET /v1/tools` (e.g.\n`\"factset__SearchEntities\": {\"enabled\": true}`). The catalog endpoint\nreturns the JSON schema for each tool's config.", "properties": { "python_code_execution": { "anyOf": [ { "$ref": "#/components/schemas/PythonCodeExecutionToolConfig" }, { "type": "null" } ], "description": "Python code execution settings \u2014 toggle code execution and chart rendering." }, "search": { "anyOf": [ { "$ref": "#/components/schemas/SearchToolConfig" }, { "type": "null" } ], "description": "Search tool configuration: query filters and ranking." } }, "title": "ToolsConfigs", "type": "object" }, "TraceQuery": { "description": "A search query executed by the agent.", "properties": { "text": { "description": "The search query text.", "title": "Text", "type": "string" } }, "required": [ "text" ], "title": "TraceQuery", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" } }, "securitySchemes": { "API Key Authentication": { "description": "API key for authentication.", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "description": "HTTP API for Bigdata Research Agent and Deep-Research capabilities", "title": "Bigdata Research Agent API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/research-agent": { "post": { "description": "Execute a research query with AI-powered analysis and real-time data. Returns a streaming response via Server-Sent Events.", "operationId": "research_agent_v1_research_agent_post", "requestBody": { "content": { "application/json": { "example": { "message": "Type your research question here. Example: Summarize recent developments in quantum computing research.", "model_name": "base", "persistence_mode": "disabled", "research_effort": "lite" }, "schema": { "$ref": "#/components/schemas/ResearchAgentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ResearchAgentResponse" }, { "type": "null" } ], "title": "Response Research Agent V1 Research Agent Post" } }, "text/event-stream": {} }, "description": "Streaming SSE response with research results." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "API Key Authentication": [] } ], "summary": "Research Agent", "tags": [ "Research Agent" ] } }, "/v1/tools": { "get": { "description": "Return the per-user catalog of tools the Research Agent can call, including each tool's JSON Schema for its `tools_configs` entry and the default configuration the server applies. Use this to discover MCP-backed connector tools or to validate `tools_configs` payloads before submitting a research request.", "operationId": "list_tools_v1_tools_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ToolDescriptor" }, "title": "Response List Tools V1 Tools Get", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "API Key Authentication": [] } ], "summary": "List Available Tools", "tags": [ "Research Agent" ] } } }, "servers": [ { "description": "Production server", "url": "https://agents.bigdata.com" } ] }