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

# Run an S&P 500 filing query

> Runs a query against S&P 500 SEC filing evidence and returns one JSON response.



## OpenAPI

````yaml /openapi.json post /query
openapi: 3.1.0
info:
  title: AI Baseline API
  description: REST contract for AI Baseline queries and metadata-filter discovery.
  version: 7.12.8
servers:
  - url: https://api-beta.ai-baseline.xyz/v2/sandp_500
    description: AI Baseline API
security:
  - ApiKeyAuth: []
paths:
  /query:
    post:
      tags:
        - Queries
      summary: Run an S&P 500 filing query
      description: >-
        Runs a query against S&P 500 SEC filing evidence and returns one JSON
        response.
      operationId: runResearchQuery
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchRequest'
            examples:
              basic:
                summary: Minimal S&P 500 evidence retrieval
                value:
                  query: >-
                    What supply chain risks did Apple disclose in its 10-K
                    filings?
              research:
                summary: Metadata-aware evidence retrieval
                value:
                  query: What are the key risks in AAPL's latest 10-K?
                  mode: research
                  effort: medium
                  metadata_filters:
                    sec_ticker: AAPL
                    sec_form_type: 10-K
                  include:
                    metadata_distribution: true
                    metadata_dashboard: true
                    summary: true
              agentic_research:
                summary: Decomposed evidence retrieval
                value:
                  query: Compare demand risks for AAPL and MSFT.
                  mode: agentic_research
                  effort: high
                  metadata_filters:
                    sec_ticker:
                      - AAPL
                      - MSFT
                  include:
                    summary: true
              retrieval_only:
                summary: Rendered evidence-only retrieval
                value:
                  query: Show evidence for AAPL supply-chain risks.
                  mode: research
                  effort: medium
                  metadata_filters:
                    sec_ticker: AAPL
                  include:
                    evidence: true
                    evidence_format: rendered
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchResponse'
        '404':
          description: Unknown domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ResearchRequest:
      properties:
        query:
          type: string
          title: Query
        mode:
          type: string
          enum:
            - basic
            - research
            - agentic_research
          title: Mode
          default: basic
        effort:
          type: string
          enum:
            - low
            - medium
            - high
          title: Effort
          default: medium
        metadata_filters:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata Filters
        include:
          $ref: '#/components/schemas/IncludeOptions'
        retrieval:
          anyOf:
            - $ref: '#/components/schemas/RetrievalControls'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - query
      title: ResearchRequest
    ResearchResponse:
      properties:
        request_id:
          type: string
          title: Request Id
        notices:
          items:
            $ref: '#/components/schemas/NoticePayload'
          type: array
          title: Notices
        metadata_distribution:
          additionalProperties: true
          type: object
          title: Metadata Distribution
        metadata_dashboard:
          type: string
          title: Metadata Dashboard
        evidence:
          type: string
          title: Evidence
        evidence_instructions:
          type: string
          title: Evidence Instructions
        agent_context:
          $ref: '#/components/schemas/AgentContextPayload'
          title: Agent Context
        summary:
          $ref: '#/components/schemas/ResponseSummary'
          title: Summary
        retrieval_plan:
          $ref: '#/components/schemas/RetrievalPlanPayload'
          title: Retrieval Plan
      additionalProperties: false
      type: object
      required:
        - request_id
      title: ResearchResponse
    ErrorResponse:
      properties:
        status_code:
          type: integer
          title: Status Code
        message:
          type: string
          title: Message
        detail:
          anyOf:
            - {}
            - type: 'null'
          title: Detail
      type: object
      required:
        - status_code
        - message
      title: ErrorResponse
    IncludeOptions:
      properties:
        evidence:
          type: boolean
          title: Evidence
          default: true
        evidence_instructions:
          type: boolean
          title: Evidence Instructions
          default: true
        agent_context:
          type: boolean
          title: Agent Context
          default: false
        evidence_format:
          type: string
          enum:
            - rendered
            - xml
          title: Evidence Format
          default: rendered
        metadata_distribution:
          type: boolean
          title: Metadata Distribution
          default: false
        metadata_dashboard:
          type: boolean
          title: Metadata Dashboard
          default: false
        summary:
          type: boolean
          title: Summary
          default: true
      additionalProperties: false
      type: object
      title: IncludeOptions
    RetrievalControls:
      properties:
        max_evidence:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Evidence
      additionalProperties: false
      type: object
      title: RetrievalControls
    NoticePayload:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      additionalProperties: false
      type: object
      required:
        - code
        - message
      title: NoticePayload
    AgentContextPayload:
      properties:
        content_type:
          type: string
          const: text/markdown
          title: Content Type
          default: text/markdown
        text:
          type: string
          title: Text
        source_fields:
          items:
            type: string
          type: array
          title: Source Fields
      additionalProperties: false
      type: object
      required:
        - text
      title: AgentContextPayload
    ResponseSummary:
      properties:
        domain:
          type: string
          title: Domain
        mode:
          type: string
          enum:
            - basic
            - research
            - agentic_research
          title: Mode
        effort:
          type: string
          enum:
            - low
            - medium
            - high
          title: Effort
        submitted_metadata_filters:
          additionalProperties: true
          type: object
          title: Submitted Metadata Filters
        applied_metadata_filters:
          additionalProperties: true
          type: object
          title: Applied Metadata Filters
        evidence_count:
          type: integer
          title: Evidence Count
        warnings:
          items:
            type: string
          type: array
          title: Warnings
      additionalProperties: false
      type: object
      required:
        - domain
        - mode
        - effort
        - evidence_count
      title: ResponseSummary
    RetrievalPlanPayload:
      properties:
        queries:
          items:
            $ref: '#/components/schemas/RetrievalPlanQueryPayload'
          type: array
          title: Queries
      additionalProperties: false
      type: object
      title: RetrievalPlanPayload
    RetrievalPlanQueryPayload:
      properties:
        query:
          type: string
          title: Query
        label:
          type: string
          title: Label
        applied_metadata_filters:
          additionalProperties: true
          type: object
          title: Applied Metadata Filters
      additionalProperties: false
      type: object
      required:
        - query
      title: RetrievalPlanQueryPayload
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````