> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Research Agent

> Execute a research query with AI-powered analysis and real-time data. Returns a streaming response via Server-Sent Events.



## OpenAPI

````yaml /api-rest/openapi/openapi_research_agent.json post /v1/research-agent
openapi: 3.1.0
info:
  description: HTTP API for Bigdata Research Agent and Deep-Research capabilities
  title: Bigdata Research Agent API
  version: 1.0.0
servers:
  - description: Production server
    url: https://agents.bigdata.com
security: []
paths:
  /v1/research-agent:
    post:
      tags:
        - Research Agent
      summary: Research Agent
      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.
              research_effort: lite
              model_name: base
              persistence_mode: disabled
            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: []
components:
  schemas:
    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
        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. Use "pro" to allow the workflow to use the most
            capable available model when higher reasoning or accuracy is
            required. LLM Model selection is dynamic and may vary based on task
            type, availability, failover, and internal performance benchmarks.
        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:
            - additionalProperties:
                $ref: '#/components/schemas/SearchToolConfig'
              propertyNames:
                const: search
              type: object
            - type: 'null'
          description: Configuration for the search tool, including filters and ranking.
          title: Tools Configs
      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:
                $ref: '#/components/schemas/ActionMessage'
              ANSWER:
                $ref: '#/components/schemas/AnswerMessage'
              AUDIT:
                $ref: '#/components/schemas/AuditMessage'
              COMPLETE:
                $ref: '#/components/schemas/CompleteMessage'
              ERROR:
                $ref: '#/components/schemas/ErrorMessage'
              GROUNDING:
                $ref: '#/components/schemas/GroundingMessage'
              LLM_RETRY:
                $ref: '#/components/schemas/LlmRetryMessage'
              PLANNING:
                $ref: '#/components/schemas/PlanningMessage'
              STRUCTURED_OUTPUT:
                $ref: '#/components/schemas/StructuredOutputMessage'
              THINKING:
                $ref: '#/components/schemas/ThinkingMessage'
              TOOL_ERROR:
                $ref: '#/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/ToolErrorMessage'
            - $ref: '#/components/schemas/PlanningMessage'
            - $ref: '#/components/schemas/LlmRetryMessage'
            - $ref: '#/components/schemas/StructuredOutputMessage'
          title: Message
      required:
        - chat_id
        - message
      title: ResearchAgentResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ModelName:
      description: >-
        Selects the model capability tier. Use "base" for the default routing
        strategy. Use "pro" to allow the workflow to use the most capable
        available model when higher reasoning or accuracy is required. LLM Model
        selection is dynamic and may vary based on task type, availability,
        failover, and internal performance benchmarks.
      enum:
        - base
        - pro
      title: ModelName
      type: string
    PersistenceMode:
      description: Controls whether conversation history is saved.
      enum:
        - enabled
        - disabled
      title: PersistenceMode
      type: string
    ResearchEffort:
      description: Controls the depth and thoroughness of the research.
      enum:
        - lite
        - standard
      title: ResearchEffort
      type: string
    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
    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
    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:
                  $ref: '#/components/schemas/TokenTierConsumption'
                pro:
                  $ref: '#/components/schemas/TokenTierConsumption'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/TokenTierConsumption'
          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
    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
    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
    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
    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
    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
    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
    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
    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
    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
              minimum: 1
              type: integer
            - type: 'null'
          description: Prioritize more recent content (1-10).
          title: Freshness Boost
        source_boost:
          anyOf:
            - maximum: 10
              minimum: 1
              type: integer
            - type: 'null'
          description: Boost results from high-quality, authoritative sources (1-10).
          title: Source Boost
      title: RankingParameters
      type: object
    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
    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
    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
    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
    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:
                  $ref: '#/components/schemas/TokenTierConsumption'
                pro:
                  $ref: '#/components/schemas/TokenTierConsumption'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/TokenTierConsumption'
          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
    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
    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:
                    $ref: '#/components/schemas/BigdataDocument'
                  EXTERNAL:
                    $ref: '#/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
    Plan:
      description: A structured research plan with ordered steps.
      properties:
        steps:
          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
    ContentFilter:
      description: Composable content filter using logical operators.
      properties:
        all_of:
          description: Match content satisfying all of these filters.
          items:
            anyOf:
              - $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:
            anyOf:
              - $ref: '#/components/schemas/DocumentIdFilter'
              - $ref: '#/components/schemas/SourceFilter'
          title: Any Of
          type: array
        none_of:
          description: Exclude content matching any of these filters.
          items:
            anyOf:
              - $ref: '#/components/schemas/DocumentIdFilter'
              - $ref: '#/components/schemas/SourceFilter'
          title: None Of
          type: array
      title: ContentFilter
      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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    StepStatus:
      description: Status of a research plan step.
      enum:
        - NOT_STARTED
        - IN_PROGRESS
        - COMPLETED
        - SKIPPED
        - FAILED
      title: StepStatus
      type: string
    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
          minimum: 1
          title: Level
          type: integer
        text:
          description: Heading text.
          minLength: 1
          title: Text
          type: string
      required:
        - text
      title: HeaderBlock
      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
    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
    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
    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
    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
    StructuredType:
      description: Types of structured data blocks.
      enum:
        - table
      title: StructuredType
      type: string
    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
  securitySchemes:
    API Key Authentication:
      description: API key for authentication.
      in: header
      name: X-API-Key
      type: apiKey

````