openapi: 3.1.0
info:
  title: Bavest API
  description: 'REST API for financial market data: equities, ETFs, funds, dividends, estimates, calendars, economic indicators, news, filings and portfolio analytics (Bavest QuantOS). Base URL `https://api.bavest.co/v2`.


    Send your API key in the `x-api-key` header on every request. Get a key at https://dashboard.bavest.co/sign-up (free trial). Most data endpoints return JSON with a `data` field; image and document endpoints can return binary content (for example, images or PDF), and MCP uses JSON-RPC. See each route''s response content type.


    Which routes a key reaches and how many calls it may make depend on its plan. `401` or `403`: the key is missing, invalid or switched off. `429` with `Limit Exceeded`: the monthly quota is used up. Any other `429`: the key is throttled, or the route is not in its plan; wait for `Retry-After` when it is sent.


    Versioning: the major version is in the path (`/v2/`); minor and patch versions are backward-compatible.'
  version: 2.2.0
  termsOfService: https://www.bavest.co/en/legal/terms-of-service
  contact:
    name: Bavest API Support
    url: https://bavest.co
    email: support@bavest.co
  license:
    name: Proprietary
    url: https://bavest.co/terms
servers:
  - url: https://api.bavest.co
    description: Production API
security:
  - apiKey: []
tags:
  - name: Account
    description: 'API health status and usage quota.


      Use these endpoints to verify API connectivity and monitor your usage against plan limits.'
  - name: Bulk
    description: 'Batch any endpoint across up to 100 symbols or ISINs in a single request.


      Results are returned in the same order as the input.'
  - name: Calendar
    description: 'Earnings, IPO, dividend, and economic event calendars.


      Filter by date range to find upcoming corporate events.'
  - name: Corporate Actions
    description: 'Stock splits, earnings events, and earnings call transcripts.


      Track all material corporate events that affect shareholder value.'
  - name: Crypto
    description: 'Cryptocurrency profiles.


      Supports major cryptocurrencies by ticker symbol (e.g., `BTC`, `ETH`).'
  - name: Dividends
    description: 'Dividend history, annual summaries, and upcoming ex-dividend dates.


      Consolidated view of dividend data across equities and calendar events.'
  - name: Economic Indicators
    description: 'Bavest V2 exposes macroeconomic data through two families of endpoints:


      - **Economy shortcuts** (`/v2/economy/{indicator}/{country}`): single-metric snapshots for CPI, GDP, inflation, interest rates, and unemployment

      - **Generic indicator** (`/v2/economy/indicator`): supported metric codes or categories, query-param driven

      - **Country discovery** (`/v2/economy/countries`): enumerate all countries with data

      - **Metric history** (`/v2/metrics/{metric_code}/history`): full time-series with cursor pagination, grouped by unit


      All endpoints accept ISO 3166-1 alpha-2 country codes (e.g., `US`, `DE`, `JP`). Each series returns one observation per reference period from the most complete upstream source.'
  - name: Equities
    description: 'Company profiles, peer comparisons, financial statements, and comprehensive metrics.


      > All equity endpoints accept `symbol` or `isin` as query parameters — e.g. `?symbol=AAPL` or `?isin=US0378331005`.'
  - name: Estimates
    description: 'Analyst consensus estimates, buy/sell recommendations, and rating changes (upgrades/downgrades).


      Data sourced from institutional analyst coverage.'
  - name: ETFs
    description: 'ETF profiles, holdings, sector/country exposure, performance metrics, risk, fees, and KID (Key Information Document) access.


      Comprehensive coverage of exchange-traded funds listed globally.'
  - name: Forex
    description: 'Foreign exchange pair quotes and OHLCV candle data.


      Use standard pair notation (e.g., `EURUSD`, `GBPJPY`).'
  - name: Funds
    description: 'Mutual fund holdings, sector/country allocation, and metrics (NAV, AUM, performance returns).


      Access fund data using ISIN identifiers.'
  - name: IPO
    description: 'Hot IPO offerings with terms, timeline milestones, multi-period financials

      (with business-segment breakdowns), and a multi-language document catalog.


      Documents support language content-negotiation with a canonical-primary

      fallback: request a `language` and each document type returns that language

      if available, otherwise the primary language.'
  - name: Filings
    description: 'Real-time regulatory filing events, starting with SEC 8-K earnings

      releases.'
  - name: News
    description: 'Stock-specific and market-wide financial news from multiple publishers.


      Articles include headline, summary, source, and publication timestamp.'
  - name: Bavest QuantOS
    description: Quantitative portfolio analytics including allocation, optimization, valuation, and sector/region breakdowns.
  - name: Reference
    description: 'Security search and stock screener.


      Search across all asset classes by name, ticker, or ISIN.'
  - name: Timeseries Data
    description: 'Net asset values (NAV) of funds and ETFs.


      Crypto and forex prices have their own groups.'
  - name: AI
    description: 'Model Context Protocol (MCP) server for AI agent integration.


      Connect any MCP compatible client (Claude, Cursor, Windsurf, or custom agents) to the full Bavest API

      through a single endpoint. All API tools are exposed automatically, no individual wiring required.'
paths:
  /v2/account/quota:
    get:
      operationId: account.quota
      summary: Usage Quota
      description: Returns current monthly usage count, limit, and remaining calls for the API key.
      tags:
        - Account
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      apiKey:
                        type: string
                        description: API Gateway key identifier
                        example: example_key_id
                      usage:
                        type: integer
                        description: API calls used in current billing period
                        example: 4521
                      limit:
                        type: integer
                        nullable: true
                        description: Monthly request limit (null if unlimited)
                        example: 100000
                      remaining:
                        type: integer
                        nullable: true
                        description: Remaining API calls (null if unlimited)
                        example: 95479
                      period:
                        type: string
                        description: Current billing period (YYYY-MM)
                        example: 2026-03
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  apiKey: example_key_id
                  usage: 289762
                  limit: 10000000
                  remaining: 9710238
                  period: 2026-03
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/account/status:
    get:
      operationId: account.status
      summary: API Status
      description: Returns API health status. Use for connectivity checks and uptime monitoring.
      tags:
        - Account
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - not_active
                          - active
                      version:
                        type: string
                        description: API version identifier
                        example: v2
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  status: active
                  version: v2
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/bulk:
    post:
      operationId: bulk.endpoint
      summary: Bulk Endpoint
      description: 'Fan out a single endpoint across up to 100 symbols or ISINs in one request. Results are returned as an array in the same order as the input.


        Provide exactly one of `symbols` or `isins`. The `params` object is merged into every invocation for shared parameters (e.g., currency, date range).'
      tags:
        - Bulk
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BulkResultItem'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        description: Bulk invocation request with symbols/ISINs, target endpoint, and optional shared parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRequest'
            examples:
              crypto_price:
                summary: Bulk crypto quotes
                value:
                  symbols:
                    - symbol: BTCUSD
                    - symbol: ETHUSD
                  endpoint: crypto_price
                  params: {}
              dividend:
                summary: Bulk dividend history
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: dividend
                  params: {}
              etf_country:
                summary: Bulk ETF country exposure
                value:
                  endpoint: etf_country
                  params: {}
                  isins:
                    - isin: IE00B4L5Y983
              etf_dividend:
                summary: Bulk ETF dividend history
                value:
                  symbols:
                    - symbol: SPY
                    - symbol: QQQ
                  endpoint: etf_dividend
                  params: {}
              etf_holdings:
                summary: Bulk ETF holdings
                value:
                  endpoint: etf_holdings
                  params: {}
                  isins:
                    - isin: IE00B4L5Y983
              etf_metrics:
                summary: Bulk ETF performance metrics
                value:
                  endpoint: etf_metrics
                  params: {}
                  isins:
                    - isin: IE00B4L5Y983
              etf_profile:
                summary: Bulk ETF profiles
                value:
                  endpoint: etf_profile
                  params: {}
                  isins:
                    - isin: IE00B4L5Y983
              etf_sector:
                summary: Bulk ETF sector exposure
                value:
                  endpoint: etf_sector
                  params: {}
                  isins:
                    - isin: IE00B4L5Y983
              etf_top_holdings:
                summary: Bulk ETF top holdings
                value:
                  endpoint: etf_top_holdings
                  params: {}
                  isins:
                    - isin: IE00B4L5Y983
              etf_top_sectors:
                summary: Bulk ETF top sectors
                value:
                  endpoint: etf_top_sectors
                  params: {}
                  isins:
                    - isin: IE00B4L5Y983
              stock_metric:
                summary: Bulk equity metrics
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: stock_metric
                  params: {}
              stock_profile:
                summary: Bulk company profiles
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: stock_profile
                  params: {}
              balance_sheet:
                summary: Bulk balance sheets
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: balance_sheet
                  params:
                    freq: annual
              cash_flow:
                summary: Bulk cash flow statements
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: cash_flow
                  params:
                    freq: annual
              income_statement:
                summary: Bulk income statements
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: income_statement
                  params:
                    freq: annual
              financials_ttm:
                summary: Bulk financials TTM
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: financials_ttm
                  params: {}
              estimates_consensus:
                summary: Bulk analyst consensus estimates
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: estimates_consensus
                  params: {}
              estimates_recommendations:
                summary: Bulk analyst recommendations
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: estimates_recommendations
                  params: {}
              dividends_history:
                summary: Bulk dividend history
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: dividends_history
                  params: {}
              news_stock:
                summary: Bulk stock news
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: news_stock
                  params:
                    limit: '5'
              market_cap:
                summary: Bulk market capitalization
                value:
                  symbols:
                    - symbol: AAPL
                    - symbol: MSFT
                  endpoint: market_cap
                  params: {}
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/calendar/earnings:
    get:
      operationId: calendar.earnings
      summary: Earnings Calendar
      description: Returns upcoming and recent earnings events across all securities.
      tags:
        - Calendar
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EarningsCalendarRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - eventType: earnings
                    date: '2026-10-02'
                    symbol: 2300.T
                    eps: null
                    epsEstimated: null
                    revenue: null
                    revenueEstimated: null
                    fiscalDateEnding: '2026-08-31'
                    time: amc
                  - eventType: earnings
                    date: '2026-10-02'
                    symbol: 3035.T
                    eps: null
                    epsEstimated: null
                    revenue: null
                    revenueEstimated: null
                    fiscalDateEnding: '2026-08-31'
                    time: amc
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 261
                  totalCount: 26030
                  parameters:
                    limit: '100'
                  time: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
        - name: symbol
          in: query
          required: false
          schema:
            type: string
          description: Only this security's events (e.g., `BMW.DE`). Omit for the whole calendar. Provide at most one of symbol or isin.
        - name: isin
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
            minLength: 12
            maxLength: 12
          description: Only this security's events, resolved to its primary listing (e.g., `DE0005190003` is `BMW.DE`). An unknown ISIN is 404. Omit for the whole calendar.
  /v2/calendar/ipo:
    get:
      operationId: calendar.ipos
      summary: IPO Calendar
      description: Returns upcoming and recent IPO events.
      tags:
        - Calendar
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IPORecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - symbol: CSQR
                    date: '2026-07-16'
                    name: Csquare, Inc.
                    exchange: null
                    numberOfShares: 50000000
                    priceLow: 23.0
                    priceHigh: 27.0
                    status: Expected
                    totalSharesValue: 1552500000.0
                  - symbol: STDN
                    date: '2026-07-16'
                    name: Standard Nuclear, Inc.
                    exchange: null
                    numberOfShares: 18250000
                    priceLow: 18.0
                    priceHigh: 21.0
                    status: Expected
                    totalSharesValue: 440737500.0
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 6
                  totalCount: 593
                  parameters:
                    limit: '100'
                  time: 6
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolFilterQuery'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/calendar/agm:
    get:
      operationId: calendar.agm
      summary: AGM Calendar
      description: Returns upcoming Annual General Meeting dates sourced from SEC DEF 14A proxy filings. Defaults to meetings from today onwards.
      tags:
        - Calendar
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AGMRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - meetingDate: '2027-06-24'
                    symbol: GHI
                    isin: US02364V2060
                    recordDate: null
                  - meetingDate: '2027-05-06'
                    symbol: MLI
                    isin: US6247561029
                    recordDate: null
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 2
                  totalCount: 191
                  parameters:
                    limit: '100'
                  time: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
        - name: symbol
          in: query
          required: false
          schema:
            type: string
          description: Only this security's events (e.g., `BMW.DE`). Omit for the whole calendar. Provide at most one of symbol or isin.
        - name: isin
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
            minLength: 12
            maxLength: 12
          description: Only this security's events, resolved to its primary listing (e.g., `DE0005190003` is `BMW.DE`). An unknown ISIN is 404. Omit for the whole calendar.
  /v2/calendar/splits:
    get:
      operationId: calendar.splits
      summary: Stock Splits Calendar
      description: Returns recent and upcoming stock split events sorted by date descending.
      tags:
        - Calendar
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SplitRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - date: '2026-11-27'
                    symbol: 8976.T
                    fromFactor: 1.0
                    toFactor: 4.0
                  - date: '2026-11-27'
                    symbol: 4616.T
                    fromFactor: 1.0
                    toFactor: 3.0
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 973
                  totalCount: 97278
                  parameters:
                    limit: '100'
                  time: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
        - name: symbol
          in: query
          required: false
          schema:
            type: string
          description: Only this security's events (e.g., `BMW.DE`). Omit for the whole calendar. Provide at most one of symbol or isin.
        - name: isin
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
            minLength: 12
            maxLength: 12
          description: Only this security's events, resolved to its primary listing (e.g., `DE0005190003` is `BMW.DE`). An unknown ISIN is 404. Omit for the whole calendar.
  /v2/corporate-actions/earnings:
    get:
      operationId: corporateActions.earnings
      summary: Earnings Events
      description: Returns historical and upcoming earnings announcement dates and results.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Corporate Actions
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EarningsCalendarRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - eventType: earnings
                    date: '2026-10-29'
                    symbol: AAPL
                    eps: null
                    epsEstimated: 1.98
                    revenue: null
                    revenueEstimated: 113210600000.0
                    fiscalDateEnding: '2026-09-27'
                    time: amc
                  - eventType: earnings
                    date: '2026-07-30'
                    symbol: AAPL
                    eps: 2.02
                    epsEstimated: 1.89
                    revenue: 109417000000.0
                    revenueEstimated: 109038900000.0
                    fiscalDateEnding: '2026-06-27'
                    time: amc
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 1
                  totalCount: 46
                  parameters:
                    limit: '100'
                    symbol: AAPL
                  time: 13
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/corporate-actions/earnings/transcript:
    get:
      operationId: corporateActions.earningsTranscript
      summary: Earnings Transcript
      description: Returns the earnings call transcript for a specific quarter.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Corporate Actions
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EarningsTranscript'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - date: '2026-07-30'
                    symbol: AAPL
                    quarter: 3
                    year: 2026
                    content: 'Suhasini Chandramouli: Good afternoon, welcome to the Apple Q3 fiscal year 2026 earnings conference call. My name is Suhasini Chandramouli, Director of Investor Relations. Today''s call is being recorded. Speaking first today is Apple CEO Tim Cook, followed by CFO Kevan Parekh. Also joining us on today''s call is incoming CEO John Ternus. After the prepared remarks, we''ll open the call to questions from analysts. Please note that some of the information you''ll hear during our discussion today will consist of forward-looking statements, including, without limitation, those regarding revenue, gros … [excerpt]'
                meta:
                  parameters:
                    quarter: '3'
                    symbol: AAPL
                    year: '2026'
                  time: 36
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - name: year
          in: query
          required: true
          schema:
            type: integer
            example: 2026
          description: Fiscal year of the earnings call (e.g., 2026). Use the periods endpoint to discover available calls.
        - name: quarter
          in: query
          required: true
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 3
              - 4
            example: 3
          description: Fiscal quarter (1-4) of the earnings call
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/corporate-actions/earnings/transcript/periods:
    get:
      operationId: corporateActions.earningsTranscriptPeriods
      summary: Earnings Transcript Periods
      description: Returns the list of year/quarter combinations that have earnings transcripts available for a symbol.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Corporate Actions
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TranscriptPeriod'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - year: 2026
                    quarter: 3
                  - year: 2026
                    quarter: 2
                meta:
                  parameters:
                    symbol: AAPL
                  time: 11
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/corporate-actions/splits:
    get:
      operationId: corporateActions.splits
      summary: Stock Splits
      description: Returns historical stock split records.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Corporate Actions
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SplitRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - date: '2020-08-31'
                    symbol: AAPL
                    fromFactor: 1
                    toFactor: 4
                  - date: '2014-06-09'
                    symbol: AAPL
                    fromFactor: 1
                    toFactor: 7
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 1
                  totalCount: 5
                  parameters:
                    limit: '100'
                    symbol: AAPL
                  time: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/crypto/quote:
    get:
      operationId: crypto.quote
      summary: Crypto Quote
      description: Returns real-time cryptocurrency quote with price, change, volume, and market cap.
      tags:
        - Crypto
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      symbol:
                        type: string
                        description: Cryptocurrency pair symbol
                        example: BTCUSD
                      name:
                        type: string
                        description: Cryptocurrency name
                        example: Bitcoin USD
                      price:
                        type: number
                        description: Current price
                        example: 67542.31
                      change:
                        type: number
                        description: Absolute price change
                        example: -1250.5
                      changePercent:
                        type: number
                        description: Price change percentage
                        example: -1.82
                      dayLow:
                        type: number
                        description: Intraday low
                        example: 66800.0
                      dayHigh:
                        type: number
                        description: Intraday high
                        example: 68900.0
                      open:
                        type: number
                        description: Opening price
                        example: 68792.81
                      previousClose:
                        type: number
                        description: Previous close price
                        example: 68792.81
                      volume:
                        type: number
                        description: 24h trading volume
                        example: 28453120000
                      marketCap:
                        type: number
                        nullable: true
                        description: Market capitalization
                        example: 1329000000000
                      timestamp:
                        type: integer
                        description: Quote timestamp (Unix epoch seconds)
                        example: 1773352065
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  symbol: BTCUSD
                  name: Bitcoin USD
                  price: 86756.99
                  change: 1907.06
                  changePercent: 2.2476
                  dayLow: 84555.46
                  dayHigh: 87209
                  open: 84849.93
                  previousClose: 84849.93
                  volume: 41500573696
                  marketCap: 1732761790904
                  timestamp: 1790949957
                meta:
                  parameters:
                    symbol: BTCUSD
                  time: 8
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/cryptoSymbolQuery'
  /v2/crypto/list:
    get:
      operationId: crypto.list
      summary: Crypto List
      description: Returns a paginated list of all available cryptocurrencies. Every pair is quoted in USD and its `symbol` can be passed to `/v2/crypto/quote` as-is.
      tags:
        - Crypto
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CryptoListItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - symbol: 00USD
                    name: 00 Token USD
                    cryptocurrency: '00'
                    currency: USD
                  - symbol: 0X0USD
                    name: 0x0.ai USD
                    cryptocurrency: 0X0
                    currency: USD
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 48
                  totalCount: 4761
                  parameters:
                    limit: '100'
                  time: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/dividends/annual:
    get:
      operationId: dividends.annual
      summary: Annual Dividend Summary
      description: Returns aggregated annual dividend totals and payment frequency.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Dividends
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AnnualDividendSummary'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  dividendFrequency: 4
                  dividends:
                    - year: 2026
                      amount: 0.53
                    - year: 2025
                      amount: 1.03
                  currency: USD
                meta:
                  parameters:
                    symbol: AAPL
                  time: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/dividends/calendar:
    get:
      operationId: dividends.calendar
      summary: Dividend Calendar
      description: 'Announced dividend events between `from` and `to`, soonest first.


        Defaults to **upcoming** events: with no `from`, the window starts today

        (UTC). Pass an explicit `from` in the past to include events that have

        already gone ex. Both dates are inclusive, so `from` equal to `to`

        returns that single day. Every page, including the cursor pages that

        follow page 1, is sorted by `date` ascending, then `symbol`.


        Scope the feed to one instrument with `symbol` or `isin` instead of

        paging the whole market. An identifier that does not resolve returns 404;

        it never falls back to the whole market. Each row carries the resolved

        `isin`, and `currency` is null when the instrument''s currency is unknown.'
      tags:
        - Dividends
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DividendRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - symbol: 0038.HK
                    date: '2026-10-02'
                    adjustedAmount: 0.08
                    amount: 0.08
                    recordDate: '2026-10-05'
                    payDate: '2026-11-13'
                    declarationDate: null
                    exDate: '2026-09-30'
                    isin: CNE100000320
                    currency: HKD
                  - symbol: 0311.HK
                    date: '2026-10-02'
                    adjustedAmount: 0.0251
                    amount: 0.0251
                    recordDate: '2026-10-06'
                    payDate: '2026-10-30'
                    declarationDate: null
                    exDate: '2026-10-05'
                    isin: KYG5697P1046
                    currency: HKD
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 54
                  totalCount: 5348
                  parameters:
                    limit: '100'
                  time: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolFilterQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/dividends/history:
    get:
      operationId: dividends.history
      summary: Dividend History
      description: 'Dividend events for one instrument, newest first, including announced

        dividends that have not been paid yet (they sort to the top).


        `from` and `to` narrow the window and are both inclusive: `from` set to

        today returns only upcoming events, `to` set to today only past ones.

        Without them the full history is returned. Cursor pages continue the

        newest-first order.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Dividends
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DividendRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - symbol: AAPL
                    date: '2026-05-11'
                    adjustedAmount: 0.27
                    amount: 0.27
                    recordDate: '2026-05-11'
                    payDate: '2026-05-14'
                    declarationDate: '2026-04-30'
                    exDate: '2026-05-11'
                    currency: USD
                  - symbol: AAPL
                    date: '2026-02-09'
                    adjustedAmount: 0.26
                    amount: 0.26
                    recordDate: '2026-02-09'
                    payDate: '2026-02-12'
                    declarationDate: '2026-01-29'
                    exDate: '2026-02-09'
                    currency: USD
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 1
                  totalCount: 91
                  parameters:
                    limit: '100'
                    symbol: AAPL
                  time: 15
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/dividends/estimates:
    get:
      operationId: dividends.estimates
      summary: Dividend Estimates
      description: 'Bavest''s per-share dividend forecast. Returns a per-share `amount` with

        `lower` and `upper` bounds, one annual estimate per `date`, newest first.

        Covers equities and ETFs. These are Bavest model forecasts, separate from

        the analyst consensus under Estimates.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Dividends
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DividendEstimatesResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  meta:
                    as_of: '2028-01-01'
                    years: 3
                  estimates:
                    - date: '2028-01-01'
                      fiscal_year: 2028
                      fiscal_year_end: '2028-09-27'
                      expected_payment_year: 2028
                      amount: 1.1377
                      lower: 0.9179
                      upper: 1.659
                      is_estimate: true
                      basis: estimate
                      source: consensus_model
                      payout_ratio: 0.1064
                      currency: USD
                      model:
                        amount: 1.058
                        lower: 1.038
                        upper: 1.081
                    - date: '2027-01-01'
                      fiscal_year: 2027
                      fiscal_year_end: '2027-09-27'
                      expected_payment_year: 2027
                      amount: 1.08
                      lower: 0.9785
                      upper: 1.3983
                      is_estimate: true
                      basis: estimate
                      source: consensus_model
                      payout_ratio: 0.1125
                      currency: USD
                      model:
                        amount: 1.053
                        lower: 1.039
                        upper: 1.069
                meta:
                  parameters:
                    symbol: AAPL
                  time: 2262
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/economy/cpi/{country}:
    get:
      operationId: economy.cpi
      summary: CPI Data
      description: 'Returns Consumer Price Index data for a country, grouped by metric. For AE, SA, QA and KW this shortcut selects CPI_WB, the annual World Bank index (2010=100), not the inflation percentage. Availability starts after the country dimensions and observations have been loaded.'
      tags:
        - Economic Indicators
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EconomyIndicatorResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  category: inflation
                  country: US
                  metrics:
                    - code: CPI
                      name: CPI All Urban Consumers (Index 1982-1984=100)
                      frequency: Monthly
                      unit: INDEX_1982
                      seriesCode: CPIAUCSL
                      data:
                        - referencePeriod: '2026-08-01'
                          value: 334.131
                        - referencePeriod: '2026-07-01'
                          value: 332.813
                    - code: CPI
                      name: CPI All Urban Consumers (Index 2015=100)
                      frequency: Monthly
                      unit: INDEX_2015
                      seriesCode: DSD_PRICES@DF_PRICES_ALL/{CC}.M.N.CPI.PA._T.N.GY
                      data:
                        - referencePeriod: '2026-02-01'
                          value: 2.414113
                        - referencePeriod: '2026-01-01'
                          value: 2.386431
                meta:
                  parameters:
                    country: US
                    metric: CPI
                  time: 40
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/countryPath'
  /v2/economy/gdp/{country}:
    get:
      operationId: economy.gdp
      summary: GDP Data
      description: 'Returns real gross domestic product data for a country, grouped by metric. For AE, SA, QA and KW this shortcut selects GDP_REAL_WB: annual GDP in constant 2015 US dollars, unscaled (not billions), rather than quarterly GDP_REAL. Source publication years can differ by country.'
      tags:
        - Economic Indicators
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EconomyIndicatorResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  category: gdp
                  country: US
                  metrics:
                    - code: GDP_REAL
                      name: Real GDP (Billions of chained 2017 USD)
                      frequency: Quarterly
                      unit: USD_REAL_BN
                      seriesCode: GDPC1
                      data:
                        - referencePeriod: '2026-04-01'
                          value: 24269.613
                        - referencePeriod: '2026-01-01'
                          value: 24180.419
                meta:
                  parameters:
                    country: US
                    metric: GDP_REAL
                  time: 47
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/countryPath'
  /v2/economy/inflation/{country}:
    get:
      operationId: economy.inflation
      summary: Inflation Data
      description: Returns inflation indicator data for a country, grouped by metric (CPI, HICP, PPI, etc.).
      tags:
        - Economic Indicators
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EconomyIndicatorResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  category: inflation
                  country: US
                  metrics:
                    - code: CPI
                      name: CPI All Urban Consumers (Index 1982-1984=100)
                      frequency: Monthly
                      unit: INDEX_1982
                      seriesCode: CPIAUCSL
                      data:
                        - referencePeriod: '2026-08-01'
                          value: 334.131
                        - referencePeriod: '2026-07-01'
                          value: 332.813
                    - code: CPI
                      name: CPI All Urban Consumers (Index 2015=100)
                      frequency: Monthly
                      unit: INDEX_2015
                      seriesCode: DSD_PRICES@DF_PRICES_ALL/{CC}.M.N.CPI.PA._T.N.GY
                      data:
                        - referencePeriod: '2026-02-01'
                          value: 2.414113
                        - referencePeriod: '2026-01-01'
                          value: 2.386431
                meta:
                  parameters:
                    country: US
                    category: inflation
                  time: 991
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/countryPath'
  /v2/economy/interest-rates/{country}:
    get:
      operationId: economy.interestRates
      summary: Interest Rate Data
      description: 'Returns central bank policy interest rate data for a country, grouped by metric. SA and KW use the BIS POLICY_RATE series (percent per annum). AE and QA are not covered by this BIS feed; no US-rate proxy is substituted.'
      tags:
        - Economic Indicators
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EconomyIndicatorResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  category: interest_rates
                  country: US
                  metrics:
                    - code: FED_FUNDS
                      name: Federal Funds Rate (Percent per annum)
                      frequency: Per decision
                      unit: PCT_PA
                      seriesCode: FEDFUNDS
                      data:
                        - referencePeriod: '2026-09-01'
                          value: 3.75
                        - referencePeriod: '2026-08-01'
                          value: 3.63
                    - code: DTB3
                      name: '3-Month Treasury Bill: Secondary Market Rate (Percent per annum)'
                      frequency: Daily
                      unit: PCT_PA
                      seriesCode: DTB3
                      data:
                        - referencePeriod: '2026-05-19'
                          value: 3.59
                        - referencePeriod: '2026-05-18'
                          value: 3.6
                meta:
                  parameters:
                    country: US
                    category: interest_rates
                  time: 3326
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/countryPath'
  /v2/economy/unemployment/{country}:
    get:
      operationId: economy.unemployment
      summary: Unemployment Data
      description: 'Returns unemployment rate data for a country, grouped by metric. For AE, SA, QA and KW this shortcut selects UNEMPLOYMENT_WB, the annual World Bank unemployment estimate, not a monthly national release.'
      tags:
        - Economic Indicators
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EconomyIndicatorResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  category: employment
                  country: US
                  metrics:
                    - code: UNEMPLOYMENT_RATE
                      name: Unemployment Rate (Percent)
                      frequency: Monthly
                      unit: PCT
                      seriesCode: UNRATE
                      data:
                        - referencePeriod: '2026-08-01'
                          value: 4.1
                        - referencePeriod: '2026-07-01'
                          value: 4.1
                meta:
                  parameters:
                    country: US
                    metric: UNEMPLOYMENT_RATE
                  time: 42
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/countryPath'
  /v2/economy/indicator:
    get:
      operationId: economy.indicator
      summary: Economy Indicator
      description: 'Returns macro-economic indicator data for a country, filtered by metric code or category. Either `metric` or `category` is required. Available categories: business_confidence, consumer_confidence, consumer_spending, economic_sentiment, employment, gdp, government, housing, income, industrial_production, inflation, interest_rates, investment, manufacturing, money_supply, trade.


        One of the query parameters `metric`, `category` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Economic Indicators
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EconomyIndicatorResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  category: inflation
                  country: US
                  metrics:
                    - code: CPI
                      name: CPI All Urban Consumers (Index 1982-1984=100)
                      frequency: Monthly
                      unit: INDEX_1982
                      seriesCode: CPIAUCSL
                      data:
                        - referencePeriod: '2026-08-01'
                          value: 334.131
                        - referencePeriod: '2026-07-01'
                          value: 332.813
                    - code: CPI
                      name: CPI All Urban Consumers (Index 2015=100)
                      frequency: Monthly
                      unit: INDEX_2015
                      seriesCode: DSD_PRICES@DF_PRICES_ALL/{CC}.M.N.CPI.PA._T.N.GY
                      data:
                        - referencePeriod: '2026-02-01'
                          value: 2.414113
                        - referencePeriod: '2026-01-01'
                          value: 2.386431
                meta:
                  parameters:
                    country: US
                    metric: CPI
                  time: 983
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - name: metric
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/EconomyMetricCode'
          description: 'Metric code to query. Either metric or category is required. See EconomyMetricCode schema for all 63 available codes.'
          example: CPI
        - name: category
          in: query
          required: false
          schema:
            type: string
            enum:
              - business_confidence
              - consumer_confidence
              - consumer_spending
              - economic_sentiment
              - employment
              - gdp
              - government
              - housing
              - income
              - industrial_production
              - inflation
              - interest_rates
              - investment
              - manufacturing
              - money_supply
              - trade
          description: "Filter by category. Returns all metrics in the category. Either metric or category is required.

            \ Example when explicitly filtering: `inflation`."
        - name: country
          in: query
          required: true
          schema:
            type: string
            example: US
          description: ISO 3166-1 alpha-2 country code (e.g. US, DE, GB, JP)
      x-one-of-parameters:
        - - metric
          - category
  /v2/economy/countries:
    get:
      operationId: economy.countries
      summary: List Available Countries
      description: 'Returns all countries that have macroeconomic data available. Use the returned ISO-2 codes as the `country` parameter for other economy endpoints.'
      tags:
        - Economic Indicators
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EconomyCountriesResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  countries:
                    - iso2: AU
                      iso3: AUS
                      name: Australia
                    - iso2: BR
                      iso3: BRA
                      name: Brazil
                meta:
                  time: 3543
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/equities/balance-sheets:
    get:
      operationId: equities.balanceSheets
      summary: Balance Sheets
      description: Returns annual or quarterly balance sheet statements with full line-item detail.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      currency:
                        type: string
                        description: Currency of reported values (ISO 4217)
                        example: USD
                      financials:
                        type: array
                        items:
                          allOf:
                            - $ref: '#/components/schemas/BalanceSheet'
                            - type: object
                              properties:
                                symbol:
                                  type: string
                                  nullable: true
                                  description: Ticker symbol the statement belongs to
                                  example: AAPL
                      provenance:
                        $ref: '#/components/schemas/StatementProvenance'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  financials:
                    - date: '2025-09-27'
                      frequency: annual
                      reportedCurrency: USD
                      cik: 320193
                      filingDate: '2025-10-31'
                      acceptedDate: '2025-10-31T06:01:26'
                      calendarYear: '2025'
                      period: FY
                      cashAndCashEquivalents: 35934000000.0
                      shortTermInvestments: 18763000000.0
                      inventory: 5718000000.0
                      otherCurrentAssets: 14585000000.0
                      goodwill: 0.0
                      intangibleAssets: 0.0
                      goodwillAndIntangibleAssets: 0.0
                      longTermInvestments: 77723000000.0
                      taxAssets: 20777000000.0
                      otherNonCurrentAssets: 62950000000.0
                      totalNonCurrentAssets: 211284000000.0
                      otherAssets: 0.0
                      totalAssets: 359241000000.0
                      shortTermDebt: 22446000000.0
                      taxPayables: 0.0
                      deferredRevenue: 9055000000.0
                      otherCurrentLiabilities: 64270000000.0
                      longTermDebt: 89931000000.0
                      deferredRevenueNonCurrent: 0.0
                      deferredTaxLiabilitiesNonCurrent: 0.0
                      otherNonCurrentLiabilities: 29946000000.0
                      totalNonCurrentLiabilities: 119877000000.0
                      otherLiabilities: 0.0
                      capitalLeaseObligations: 13720000000.0
                      totalLiabilities: 285508000000.0
                      preferredStock: 0.0
                      commonStock: 93568000000.0
                      retainedEarnings: -14264000000.0
                      otherTotalStockholdersEquity: 0.0
                      totalStockholdersEquity: 73733000000.0
                      minorityInterest: 0.0
                      totalEquity: 73733000000.0
                      totalLiabilitiesAndTotalEquity: 359241000000.0
                      totalInvestments: 96486000000.0
                      totalDebt: 112377000000.0
                      netDebt: 76443000000.0
                      accountsPayable: 69860000000.0
                      cashShortTermInvestments: 54697000000.0
                      currentAssets: 147957000000.0
                      currentLiabilities: 165631000000.0
                      liabilitiesShareholdersEquity: 359241000000.0
                      otherEquity: -5571000000.0
                      propertyPlantEquipment: 49834000000.0
                      totalReceivables: 72957000000.0
                      link: https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm
                      finalLink: https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm
                      isGapData: false
                      symbol: AAPL
                    - date: '2024-09-28'
                      frequency: annual
                      reportedCurrency: USD
                      cik: 320193
                      filingDate: '2024-11-01'
                      acceptedDate: '2024-11-01T06:01:36'
                      calendarYear: '2024'
                      period: FY
                      cashAndCashEquivalents: 29943000000.0
                      shortTermInvestments: 35228000000.0
                      inventory: 7286000000.0
                      otherCurrentAssets: 14287000000.0
                      goodwill: 0.0
                      intangibleAssets: 0.0
                      goodwillAndIntangibleAssets: 0.0
                      longTermInvestments: 91479000000.0
                      taxAssets: 19499000000.0
                      otherNonCurrentAssets: 55335000000.0
                      totalNonCurrentAssets: 211993000000.0
                      otherAssets: 0.0
                      totalAssets: 364980000000.0
                      shortTermDebt: 22511000000.0
                      taxPayables: 26601000000.0
                      deferredRevenue: 8249000000.0
                      otherCurrentLiabilities: 50071000000.0
                      longTermDebt: 96548000000.0
                      deferredRevenueNonCurrent: 0.0
                      deferredTaxLiabilitiesNonCurrent: 0.0
                      otherNonCurrentLiabilities: 35090000000.0
                      totalNonCurrentLiabilities: 131638000000.0
                      otherLiabilities: 0.0
                      capitalLeaseObligations: 12430000000.0
                      totalLiabilities: 308030000000.0
                      preferredStock: 0.0
                      commonStock: 83276000000.0
                      retainedEarnings: -19154000000.0
                      otherTotalStockholdersEquity: 0.0
                      totalStockholdersEquity: 56950000000.0
                      minorityInterest: 0.0
                      totalEquity: 56950000000.0
                      totalLiabilitiesAndTotalEquity: 364980000000.0
                      totalInvestments: 126707000000.0
                      totalDebt: 119059000000.0
                      netDebt: 89116000000.0
                      accountsPayable: 68960000000.0
                      cashShortTermInvestments: 65171000000.0
                      currentAssets: 152987000000.0
                      currentLiabilities: 176392000000.0
                      liabilitiesShareholdersEquity: 364980000000.0
                      otherEquity: -7172000000.0
                      propertyPlantEquipment: 45680000000.0
                      totalReceivables: 66243000000.0
                      link: https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/0000320193-24-000123-index.htm
                      finalLink: https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm
                      isGapData: false
                      symbol: AAPL
                  currency: USD
                meta:
                  parameters:
                    freq: annual
                    symbol: AAPL
                  time: 14
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/frequencyQuery'
        - $ref: '#/components/parameters/statementProvenanceQuery'
        - $ref: '#/components/parameters/fieldsQueryBalanceSheet'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/cash-flow:
    get:
      operationId: equities.cashFlows
      summary: Cash Flow Statements
      description: Returns annual or quarterly cash flow statements.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      currency:
                        type: string
                        description: Currency of reported values (ISO 4217)
                        example: USD
                      financials:
                        type: array
                        items:
                          allOf:
                            - $ref: '#/components/schemas/CashFlowStatement'
                            - type: object
                              properties:
                                symbol:
                                  type: string
                                  nullable: true
                                  description: Ticker symbol the statement belongs to
                                  example: AAPL
                      provenance:
                        $ref: '#/components/schemas/StatementProvenance'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  financials:
                    - date: '2025-09-27'
                      frequency: annual
                      salesMaturitiesOfInvestments: 53797000000.0
                      commonStockIssued: 0.0
                      otherWorkingCapital: -20273000000.0
                      cik: 320193
                      cashAtBeginningOfPeriod: 29943000000.0
                      filingDate: '2025-10-31'
                      link: https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm
                      changeInCash: 5991000000.0
                      inventory: 1400000000.0
                      acceptedDate: '2025-10-31T06:01:26'
                      stockBasedCompensation: 12863000000.0
                      accountsReceivables: -7029000000.0
                      freeCashFlow: 98767000000.0
                      netCashProvidedByOperatingActivities: 111482000000.0
                      purchasesOfInvestments: -24407000000.0
                      otherFinancingActivities: -6071000000.0
                      changesInWorkingCapital: -25000000000.0
                      issuanceReductionCapitalStock: -90711000000.0
                      netCashFinancingActivities: -120686000000.0
                      otherInvestingActivities: -1480000000.0
                      debtRepayment: -8483000000.0
                      acquisitionsNet: 0.0
                      cashAtEndOfPeriod: 35934000000.0
                      otherNonCashItems: -89000000.0
                      period: FY
                      effectOfForexChangesOnCash: 0.0
                      capex: -12715000000.0
                      calendarYear: '2025'
                      depreciationAmortization: 11698000000.0
                      cashDividendsPaid: -15421000000.0
                      netInvestingCashFlow: 15195000000.0
                      reportedCurrency: USD
                      netIncome: 112010000000.0
                      investmentsInPropertyPlantAndEquipment: -12715000000.0
                      finalLink: https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm
                      deferredTaxesInvestmentTaxCredit: 0.0
                      accountsPayables: 902000000.0
                      netOperatingCashFlow: 111482000000.0
                      isGapData: false
                      symbol: AAPL
                    - date: '2024-09-28'
                      frequency: annual
                      salesMaturitiesOfInvestments: 62346000000.0
                      commonStockIssued: 0.0
                      otherWorkingCapital: 3821000000.0
                      cik: 320193
                      cashAtBeginningOfPeriod: 30737000000.0
                      filingDate: '2024-11-01'
                      link: https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/0000320193-24-000123-index.htm
                      changeInCash: -794000000.0
                      inventory: -1046000000.0
                      acceptedDate: '2024-11-01T06:01:36'
                      stockBasedCompensation: 11688000000.0
                      accountsReceivables: -5144000000.0
                      freeCashFlow: 108807000000.0
                      netCashProvidedByOperatingActivities: 118254000000.0
                      purchasesOfInvestments: -48656000000.0
                      otherFinancingActivities: -5802000000.0
                      changesInWorkingCapital: 3651000000.0
                      issuanceReductionCapitalStock: -94949000000.0
                      netCashFinancingActivities: -121983000000.0
                      otherInvestingActivities: -1308000000.0
                      debtRepayment: -5998000000.0
                      acquisitionsNet: 0.0
                      cashAtEndOfPeriod: 29943000000.0
                      otherNonCashItems: -2266000000.0
                      period: FY
                      effectOfForexChangesOnCash: 0.0
                      capex: -9447000000.0
                      calendarYear: '2024'
                      depreciationAmortization: 11445000000.0
                      cashDividendsPaid: -15234000000.0
                      netInvestingCashFlow: 2935000000.0
                      reportedCurrency: USD
                      netIncome: 93736000000.0
                      investmentsInPropertyPlantAndEquipment: -9447000000.0
                      finalLink: https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm
                      deferredTaxesInvestmentTaxCredit: 0.0
                      accountsPayables: 6020000000.0
                      netOperatingCashFlow: 118254000000.0
                      isGapData: false
                      symbol: AAPL
                  currency: USD
                meta:
                  parameters:
                    freq: annual
                    symbol: AAPL
                  time: 17
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/frequencyQuery'
        - $ref: '#/components/parameters/statementProvenanceQuery'
        - $ref: '#/components/parameters/fieldsQueryCashFlow'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/logo:
    get:
      operationId: equities.logo
      summary: Company Logo
      description: Returns the company logo as a PNG image.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Equities
      responses:
        '200':
          description: Company logo (image/png)
          content:
            image/png:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/profile:
    get:
      operationId: equities.profile
      summary: Company Profile
      description: 'Returns company identity, classification, and market data.


        > This endpoint is equity-specific. For ETF or fund profiles, use the ETF or Fund domain.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CompanyProfile'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  symbol: AAPL
                  companyName: Apple Inc.
                  description: 'Apple Inc. is a global technology corporation that specializes in the conceptualization, production, and sale of a diverse suite of electronic devices. Its comprehensive hardware lineup features the well-known iPhone smartphones, Mac personal computers, and versatile iPad tablets. The company also supplies a range of wearables, smart home products, and accessories, including AirPods, Apple TV, Apple Watch, items from the Beats brand, and HomePod speakers. Beyond its device offerings, Apple delivers essential support services like AppleCare and robust cloud solutions. It oversees key digital platforms, prominently the App Store, which acts as a central hub for customers to discover and download countless applications and digital content, from e-books and music to videos, games, and podcasts. The company also generates revenue via advertising, leveraging both its proprietary ad platforms and third-party licensing deals. Apple''s ecosystem is further bolstered by a wide array of subscription-based services: Apple Arcade for gaming, Apple Fitness+ for personalized wellness, Apple Music for curated audio experiences and on-demand radio, Apple News+ for access to news and magazines, and Apple TV+ for exclusive original video programming. Its financial services portfolio includes the co-branded Apple Card and the mobile payment system, Apple Pay. Additionally, Apple strategically licenses its intellectual property. The company serves a broad clientele that spans individual consumers, small and medium-sized enterprises, as well as institutional clients in the education, corporate, and governmental sectors. Products are distributed through a multi-channel strategy, utilizing Apple''s own physical retail locations and online storefronts, a dedicated direct sales team, and collaborations with external partners such as mobile network providers, wholesalers, general retailers, and authorized resellers. The App Store additionally functions as the primary conduit for third-party applications designed for its devices. Founded in 1976, Apple Inc. is headquartered in Cupertino, California.'
                  ceo: John Ternus
                  sector: Technology
                  industry: Consumer Electronics
                  country: US
                  state: CA
                  city: Cupertino
                  address: One Apple Park Way
                  zip: '95014'
                  phone: (408) 996-1010
                  website: https://www.apple.com
                  exchange: NASDAQ Global Select
                  exchangeShortName: NASDAQ
                  isin: US0378331005
                  cik: 320193
                  ipo: '1980-12-12'
                  currency: USD
                  employeeTotal: 166000
                  isActivelyTrading: true
                  isAdr: false
                meta:
                  parameters:
                    symbol: AAPL
                  time: 13
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/metrics/names:
    get:
      operationId: equities.metric_names
      summary: Equity Metric Names
      description: Returns registered equity metric names with their unit, description and -- per name -- which reporting bases GET /equities/metrics/history can actually serve. Every name here is available as a latest value on GET /equities/metrics; `bases` is narrower, because history is materialized per basis. Filter with `hasHistory` or `basis` to get only the names a history integration can rely on. No security identifier required.
      tags:
        - Equities
      parameters:
        - name: hasHistory
          in: query
          required: false
          schema:
            type: boolean
          description: When true, return only names with at least one materialized basis; when false, only names without one. Omit for all names.
        - name: basis
          in: query
          required: false
          schema:
            type: string
            enum:
              - FY
              - Q1
              - Q2
              - Q3
              - Q4
              - H1
              - H2
              - TTM
          description: Return only names materialized on this reporting basis. A basis that is valid but not yet materialized returns an empty list with count 0 rather than an error, mirroring how the history endpoint answers with a warning instead of a 404.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Number of metric names in this response, after any hasHistory/basis filter.
                        example: 103
                      metrics:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Canonical metric name (snake_case)
                              example: pe_ratio
                            unit:
                              type: string
                              description: Unit type for the metric
                              example: ratio
                            description:
                              type: string
                              description: Human-readable description of the metric
                              example: Price-to-Earnings Ratio (P/E)
                            bases:
                              type: array
                              description: Reporting bases GET /equities/metrics/history can serve for this name. Empty means the name has a latest value but no history yet. A *_ttm name carries TTM and nothing else, since no other basis exists for it.
                              items:
                                type: string
                                enum:
                                  - FY
                                  - Q1
                                  - Q2
                                  - Q3
                                  - Q4
                                  - H1
                                  - H2
                                  - TTM
                              example:
                                - TTM
                            hasHistory:
                              type: boolean
                              description: Convenience flag, true exactly when `bases` is non-empty.
                              example: true
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  count: 192
                  metrics:
                    - name: 10y_dividend_growth
                      unit: percentage
                      description: Dividend Growth (10Y)
                      bases: []
                      hasHistory: false
                    - name: 10y_equity_growth
                      unit: percentage
                      description: Equity Growth (10Y)
                      bases:
                        - FY
                      hasHistory: true
                meta:
                  time: 2106
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
  /v2/equities/exports:
    get:
      operationId: equities.exportLatest
      summary: Equity Metrics History Export
      description: Returns time-limited download links for this account's pre-materialized equity-metrics history export (Parquet, one part per metric) plus its manifest. The export is produced by a batch job and scoped to the caller's API key; no identifier is required. If no export has been materialized yet, the response contains an empty parts list and a warning.
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      clientId:
                        type: string
                        description: The account (API-key id) the export is scoped to
                      generatedAt:
                        type: string
                        description: When the export was materialized (ISO-8601)
                      format:
                        type: string
                        example: parquet
                      schema:
                        type: array
                        items:
                          type: string
                        description: Column order of every part file
                      rows:
                        type: integer
                        description: Total rows across all parts
                      expiresInSeconds:
                        type: integer
                        description: Lifetime of the returned presigned URLs
                        example: 3600
                      manifestUrl:
                        type: string
                        description: Presigned URL for the manifest.json
                      parts:
                        type: array
                        items:
                          type: object
                          properties:
                            metricName:
                              type: string
                              example: roe_ttm
                            url:
                              type: string
                              description: Presigned URL for that metric's Parquet part
                      warning:
                        type: string
                        description: Present only when no export is materialized yet
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: equities.exportSubmit
      summary: Submit Equity Data Export
      description: Submit an asynchronous export job for this account. Choose symbols and/or isins (at least one, at most 100 together), optional metrics and a from/to window; the Parquet export is prepared asynchronously, then poll GET /equities/exports/{exportId} for signed download links. symbols and isins union. A request with neither is a 400. Scoped to the caller's API key.
      tags:
        - Equities
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                metrics:
                  type: array
                  items:
                    type: string
                symbols:
                  type: array
                  items:
                    type: string
                isins:
                  type: array
                  items:
                    type: string
                from:
                  type: string
                  format: date
                to:
                  type: string
                  format: date
      responses:
        '200':
          description: Job accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      exportId:
                        type: string
                      assetClass:
                        type: string
                        example: equity
                      status:
                        type: string
                        example: pending
                      poll:
                        type: string
                        description: Poll this path for status and links
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v2/equities/metrics:
    get:
      operationId: equities.metrics
      summary: Comprehensive Metrics
      description: Returns comprehensive per-metric financial data with validity flags, descriptions, and units. Supports optional currency conversion. Results are paginated (default 50 metrics per page, max 200).


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EquityMetrics'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  latestDate: '2026-10-02'
                  metrics:
                    - metricId: 10y_dividend_growth
                      metricName: 10y_dividend_growth
                      value: 85.8023
                      date: '2025-09-27'
                      valid: true
                      reason: null
                      rootCause: null
                      description: Dividend Growth (10Y) = (dps_last - dps_first) / |dps_first| * 100
                      unit: PERCENTAGE
                      currency: USD
                    - metricId: 10y_equity_growth
                      metricName: 10y_equity_growth
                      value: -38.2238
                      date: '2025-09-27'
                      valid: true
                      reason: null
                      rootCause: null
                      description: Equity Growth (10Y) = (equity_last - equity_first) / |equity_first| * 100
                      unit: PERCENTAGE
                      currency: USD
                meta:
                  page: 1
                  pageSize: 50
                  totalPages: 4
                  totalCount: 189
                  parameters:
                    limit: '50'
                    symbol: AAPL
                  time: 70
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - name: currency
          in: query
          required: false
          schema:
            type: string
          description: 'Target currency for monetary values (ISO 4217). Converts from reporting currency if different. Example when explicitly filtering: `USD`.'
        - $ref: '#/components/parameters/fieldsQueryMetrics'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 50
            minimum: 1
            maximum: 200
          description: Maximum number of metrics to return per page (default 50, max 200)
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 0
            minimum: 0
          description: Number of metrics to skip for pagination (default 0)
        - $ref: '#/components/parameters/cursorQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/metrics/history:
    get:
      operationId: equities.metricsHistory
      summary: Metric History
      description: Returns one statement-derived metric (ratios, margins, growth and every *_ttm name) as a series of points, one per fiscal period end, newest first. Suppressed periods are returned as explicit null points with a reason instead of being omitted, so point counts stay stable for mirrors; see the Metric History guide for basis, vintage and TTM-overlap semantics.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      metric:
                        type: object
                        properties:
                          id:
                            type: string
                            example: roe_ttm
                          name:
                            type: string
                            example: roe_ttm
                          unit:
                            type: string
                            nullable: true
                            example: RATIO
                          currency:
                            type: string
                            nullable: true
                            example: USD
                          calcVersion:
                            type: string
                            nullable: true
                            example: '2026.08'
                      basis:
                        type: string
                        enum:
                          - FY
                          - Q1
                          - Q2
                          - Q3
                          - Q4
                          - H1
                          - H2
                          - TTM
                      vintage:
                        type: string
                        enum:
                          - MR
                      warning:
                        type: string
                        description: Present when no history is materialized yet for this security/metric/basis.
                      syncCursor:
                        type: string
                        format: date-time
                        nullable: true
                        description: Latest change time across the whole series (not only the returned points). Pass it as `changedSince` on the next call. Null when no history is materialized.
                        example: '2026-07-22T21:42:19.701813+00:00'
                      points:
                        type: array
                        items:
                          type: object
                          properties:
                            periodEnd:
                              type: string
                              format: date
                            periodLabel:
                              type: string
                            calendarPeriod:
                              type: string
                              description: Calendar bucket the fiscal point belongs to, derived from the real filed period dates. Sub-annual points take the calendar quarter of their period end (CY2025Q3); annual points take the calendar year holding the majority of the fiscal year, so a non-December year-end aligns with December filers. Labeling only -- no value is interpolated across fiscal boundaries.
                              example: CY2025Q3
                            value:
                              type: number
                              nullable: true
                            valid:
                              type: boolean
                            updatedAt:
                              type: string
                              format: date-time
                              nullable: true
                              description: When this point's value last changed in our store.
                            reason:
                              type: string
                              description: Why the point is null (only on suppressed points).
                            rootCause:
                              type: string
                              description: Detail behind the suppression (only on suppressed points).
                            provenance:
                              type: object
                              description: Present only when provenance=true.
                              properties:
                                knownAt:
                                  type: string
                                  format: date-time
                                  nullable: true
                                  description: When Bavest first observed the currently served value. Null when observation history is unavailable for this security.
                                firstKnownAt:
                                  type: string
                                  format: date-time
                                  nullable: true
                                  description: When we first observed any value for this period.
                                restated:
                                  type: boolean
                                  description: True when more than one distinct value has been observed for this period. For TTM it flags the anchor quarter.
                                acceptedDate:
                                  type: string
                                  format: date-time
                                  nullable: true
                                  description: Vendor-reported acceptance date. For non-SEC filings, this date may match the period end and is not a reliable filing timestamp. It does not indicate when the data became available to Bavest; use `knownAt` when available.
                                filingDate:
                                  type: string
                                  format: date
                                  nullable: true
                                  description: Vendor-reported filing date. For non-SEC filings, this date may match the period end and is not a reliable filing timestamp. It does not indicate when the data became available to Bavest; use `knownAt` when available.
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  metric:
                    id: roe_ttm
                    name: roe_ttm
                    unit: RATIO
                    currency: null
                    calcVersion: '2026.07'
                  basis: TTM
                  vintage: MR
                  syncCursor: '2026-08-31T07:51:48.126480+00:00'
                  points:
                    - periodEnd: '2026-06-27'
                      periodLabel: TTM
                      calendarPeriod: CY2026Q2
                      value: 1.1991
                      valid: true
                      updatedAt: '2026-08-31T07:51:48.126480+00:00'
                    - periodEnd: '2026-03-28'
                      periodLabel: TTM
                      calendarPeriod: CY2026Q1
                      value: 1.151
                      valid: true
                      updatedAt: '2026-08-31T07:51:47.732996+00:00'
                meta:
                  parameters:
                    name: roe_ttm
                    symbol: AAPL
                  time: 2276
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - name: name
          in: query
          required: true
          schema:
            type: string
            example: roe_ttm
          description: Metric name. Discover valid names via GET /equities/metrics/names.
        - name: basis
          in: query
          required: false
          schema:
            type: string
            enum:
              - FY
              - Q1
              - Q2
              - Q3
              - Q4
              - H1
              - H2
              - TTM
          description: Reporting basis. Defaults to TTM for *_ttm names, FY otherwise.
        - name: vintage
          in: query
          required: false
          schema:
            type: string
            enum:
              - MR
            default: MR
          description: MR = most recent restated statements. AR / as_of point-in-time replay is not yet enabled.
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Earliest period end (inclusive).
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Latest period end (inclusive).
        - name: provenance
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: When true, each point carries a provenance block (knownAt, restated, and the vendor's acceptedDate/filingDate claim). Empty when observation history is unavailable for the security.
        - name: changedSince
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Incremental sync. Returns only points whose value changed at or after this ISO-8601 timestamp. Pass the `syncCursor` of the previous response; points upsert on periodEnd, so re-pulling an overlap is harmless.
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/financials-ttm:
    get:
      operationId: equities.financialsTtm
      summary: Financials Trailing Twelve Months
      description: Returns the most recent TTM snapshot across all three financial statements.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      bs:
                        description: Balance sheet (trailing twelve months)
                        $ref: '#/components/schemas/BalanceSheet'
                      cf:
                        description: Cash flow statement (trailing twelve months)
                        $ref: '#/components/schemas/CashFlowStatement'
                      ic:
                        description: Income statement (trailing twelve months)
                        $ref: '#/components/schemas/IncomeStatement'
                      currency:
                        type: string
                        description: Reporting currency (ISO 4217)
                      date:
                        type: string
                        format: date
                        description: TTM period end date
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  bs:
                    cashAndCashEquivalents: 39280750000.0
                    shortTermInvestments: 23846750000.0
                    cashShortTermInvestments: 63127500000.0
                    inventory: 7358000000.0
                    otherCurrentAssets: 15589000000.0
                    currentAssets: 149998250000.0
                    goodwill: 0.0
                    intangibleAssets: 10419000000.0
                    goodwillAndIntangibleAssets: 10419000000.0
                    longTermInvestments: 79454250000.0
                    taxAssets: 5194250000.0
                    otherNonCurrentAssets: 77770750000.0
                    totalNonCurrentAssets: 223223250000.0
                    otherAssets: 0.0
                    totalAssets: 373221500000.0
                    shortTermDebt: 14886000000.0
                    accountsPayable: 65580250000.0
                    taxPayables: 0.0
                    deferredRevenue: 9334250000.0
                    otherCurrentLiabilities: 63190750000.0
                    currentLiabilities: 152991250000.0
                    longTermDebt: 78090000000.0
                    deferredRevenueNonCurrent: 0.0
                    deferredTaxLiabilitiesNonCurrent: 0.0
                    otherNonCurrentLiabilities: 48156750000.0
                    totalNonCurrentLiabilities: 126246750000.0
                    otherLiabilities: 0.0
                    capitalLeaseObligations: 3430000000.0
                    totalLiabilities: 279238000000.0
                    preferredStock: 0.0
                    commonStock: 97249500000.0
                    retainedEarnings: 1811000000.0
                    otherTotalStockholdersEquity: 0.0
                    totalStockholdersEquity: 93983500000.0
                    minorityInterest: 0.0
                    totalEquity: 93983500000.0
                    otherEquity: -5077000000.0
                    totalLiabilitiesAndTotalEquity: 373221500000.0
                    liabilitiesShareholdersEquity: 373221500000.0
                    totalInvestments: 103301000000.0
                    totalDebt: 92976000000.0
                    netDebt: 53695250000.0
                    propertyPlantEquipment: 50385000000.0
                    totalReceivables: 63923750000.0
                  cf:
                    inventory: -5284000000.0
                    netIncome: 128930000000.0
                    freeCashFlow: 136683000000.0
                    depreciationAmortization: 13100000000.0
                    stockBasedCompensation: 13706000000.0
                    accountsReceivables: -12282000000.0
                    accountsPayables: 14178000000.0
                    otherNonCashItems: -378000000.0
                    deferredTaxesInvestmentTaxCredit: 0.0
                    changesInWorkingCapital: -8634000000.0
                    otherWorkingCapital: -5246000000.0
                    netCashProvidedByOperatingActivities: 146724000000.0
                    netOperatingCashFlow: 146724000000.0
                    acquisitionsNet: 0.0
                    investmentsInPropertyPlantAndEquipment: -10041000000.0
                    capex: -10041000000.0
                    purchasesOfInvestments: -55568000000.0
                    salesMaturitiesOfInvestments: 46496000000.0
                    otherInvestingActivities: -2285000000.0
                    netInvestingCashFlow: -21398000000.0
                    debtRepayment: -17274000000.0
                    commonStockIssued: 0.0
                    issuanceReductionCapitalStock: -82226000000.0
                    cashDividendsPaid: -15640000000.0
                    otherFinancingActivities: -6911000000.0
                    netCashFinancingActivities: -122051000000.0
                    effectOfForexChangesOnCash: 0.0
                    changeInCash: 3275000000.0
                    cashAtBeginningOfPeriod: 40773000000.0
                    cashAtEndOfPeriod: 41591750000.0
                  ic:
                    revenue: 466823000000.0
                    costOfGoodsSold: 239700000000.0
                    grossIncome: 227123000000.0
                    generalAndAdministrativeExpenses: 2095000000.0
                    sellingAndMarketingExpenses: 5397000000.0
                    sgaExpense: 29363000000.0
                    otherExpenses: 0.0
                    costAndExpenses: 311964000000.0
                    totalOperatingExpense: 72264000000.0
                    researchDevelopment: 42901000000.0
                    interestIncome: 0.0
                    interestExpense: 0.0
                    depreciationAndAmortization: 13100000000.0
                    totalOtherIncomeExpensesNet: 1047000000.0
                    ebit: 154859000000.0
                    ebitda: 168486000000.0
                    pretaxIncome: 155906000000.0
                    provisionForIncomeTaxes: 26976000000.0
                    netIncome: 128930000000.0
                    eps: 8.76
                    dilutedEps: 8.73
                    weightedAverageShsOut: 14774972750.0
                    dilutedAverageSharesOutstanding: 14833367500.0
                    grossProfitRatio: 0.4867
                    operatingIncomeRatio: 0.3298
                    incomeBeforeTaxRatio: 0.3322
                    netIncomeRatio: 0.2748
                    ebitdaRatio: 0.3595
                  currency: USD
                  date: '2026-06-27'
                meta:
                  parameters:
                    symbol: AAPL
                  time: 35
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/fieldsQueryFinancialsTtm'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/income-statement:
    get:
      operationId: equities.incomeStatements
      summary: Income Statements
      description: Returns annual or quarterly income statements.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      currency:
                        type: string
                        description: Currency of reported values (ISO 4217)
                        example: USD
                      financials:
                        type: array
                        items:
                          allOf:
                            - $ref: '#/components/schemas/IncomeStatement'
                            - type: object
                              properties:
                                symbol:
                                  type: string
                                  nullable: true
                                  description: Ticker symbol the statement belongs to
                                  example: AAPL
                      provenance:
                        $ref: '#/components/schemas/StatementProvenance'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  financials:
                    - date: '2025-09-27'
                      frequency: annual
                      reportedCurrency: USD
                      cik: 320193
                      filingDate: '2025-10-31'
                      acceptedDate: '2025-10-31T06:01:26'
                      calendarYear: '2025'
                      period: FY
                      revenue: 416161000000.0
                      grossProfitRatio: 0.4691
                      generalAndAdministrativeExpenses: 8077000000.0
                      sellingAndMarketingExpenses: 19524000000.0
                      otherExpenses: 0.0
                      costAndExpenses: 283111000000.0
                      interestIncome: 0.0
                      interestExpense: 0.0
                      depreciationAndAmortization: 11698000000.0
                      ebitda: 144427000000.0
                      ebitdaRatio: 0.347
                      operatingIncomeRatio: 0.3197
                      totalOtherIncomeExpensesNet: -321000000.0
                      incomeBeforeTaxRatio: 0.3189
                      netIncome: 112010000000.0
                      netIncomeRatio: 0.2692
                      eps: 7.49
                      weightedAverageShsOut: 14948500000.0
                      costOfGoodsSold: 220960000000.0
                      dilutedAverageSharesOutstanding: 15004697000.0
                      dilutedEps: 7.46
                      ebit: 133050000000.0
                      grossIncome: 195201000000.0
                      pretaxIncome: 132729000000.0
                      provisionForIncomeTaxes: 20719000000.0
                      researchDevelopment: 34550000000.0
                      sgaExpense: 27601000000.0
                      totalOperatingExpense: 62151000000.0
                      link: https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm
                      finalLink: https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm
                      isGapData: false
                      symbol: AAPL
                    - date: '2024-09-28'
                      frequency: annual
                      reportedCurrency: USD
                      cik: 320193
                      filingDate: '2024-11-01'
                      acceptedDate: '2024-11-01T06:01:36'
                      calendarYear: '2024'
                      period: FY
                      revenue: 391035000000.0
                      grossProfitRatio: 0.4621
                      generalAndAdministrativeExpenses: 7458000000.0
                      sellingAndMarketingExpenses: 18639000000.0
                      otherExpenses: 0.0
                      costAndExpenses: 267819000000.0
                      interestIncome: 0.0
                      interestExpense: 0.0
                      depreciationAndAmortization: 11445000000.0
                      ebitda: 134930000000.0
                      ebitdaRatio: 0.3451
                      operatingIncomeRatio: 0.3151
                      totalOtherIncomeExpensesNet: 269000000.0
                      incomeBeforeTaxRatio: 0.3158
                      netIncome: 93736000000.0
                      netIncomeRatio: 0.2397
                      eps: 6.11
                      weightedAverageShsOut: 15343783000.0
                      costOfGoodsSold: 210352000000.0
                      dilutedAverageSharesOutstanding: 15408095000.0
                      dilutedEps: 6.08
                      ebit: 123216000000.0
                      grossIncome: 180683000000.0
                      pretaxIncome: 123485000000.0
                      provisionForIncomeTaxes: 29749000000.0
                      researchDevelopment: 31370000000.0
                      sgaExpense: 26097000000.0
                      totalOperatingExpense: 57467000000.0
                      link: https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/0000320193-24-000123-index.htm
                      finalLink: https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm
                      isGapData: false
                      symbol: AAPL
                  currency: USD
                meta:
                  parameters:
                    freq: annual
                    symbol: AAPL
                  time: 18
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/frequencyQuery'
        - $ref: '#/components/parameters/statementProvenanceQuery'
        - $ref: '#/components/parameters/fieldsQueryIncomeStatement'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/market-cap:
    get:
      operationId: equities.marketCap
      summary: Market Capitalization
      description: 'Returns the current market capitalization for an equity.


        The currency is not fixed per security: since 1 Sep 2026 new values are

        in the filer''s reporting currency where one is on file, otherwise EUR;

        not the listing currency. Read `metricCurrency` rather than assuming

        EUR, USD or the listing currency. It is the same series

        served as `market_cap` by `/v2/equities/metrics`.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MarketCapSnapshot'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  metricValue: 4884824000000.0
                  metricCurrency: USD
                  metricDate: '2026-10-01T00:00:00'
                meta:
                  parameters:
                    symbol: AAPL
                  time: 16
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/market-cap/history:
    get:
      operationId: equities.marketCapHistory
      summary: Market Capitalization History
      description: 'Returns historical market capitalization values for an equity.


        Each point carries its own `metricCurrency`. The currency can change

        within one history (earlier points may be in the listing currency or

        EUR, points from 1 Sep 2026 in the filer''s reporting currency where one

        is on file, otherwise EUR), so do not compare values across points

        without reading it.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MarketCapRecord'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - metricValue: 4884824000000.0
                    metricDate: '2026-10-01T00:00:00'
                  - metricValue: 4806746300000.0
                    metricDate: '2026-09-30T00:00:00'
                meta:
                  parameters:
                    symbol: AAPL
                  time: 20
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/peers:
    get:
      operationId: equities.peers
      summary: Peer Companies
      description: Returns a list of peer company tickers based on sector and market cap similarity.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - Equities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                      description: Peer company ticker symbol
                      example: GOOGL
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - GOOGL
                  - NVDA
                meta:
                  parameters:
                    symbol: AAPL
                  time: 13
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/securities/nav:
    get:
      operationId: securities.nav
      summary: Security NAV
      description: 'Returns the current Net Asset Value (NAV) for securities with NAV data, including ETFs, ETPs, ETNs and mutual funds. Returns 404 for security types that do not carry a NAV (e.g. stocks).


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Timeseries Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/NavResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  nav: 145.4398
                  currency: USD
                  date: '2026-10-01'
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 12
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/equities/exports/{exportId}:
    get:
      operationId: equities.exportStatus
      summary: Equities Metrics History Export Status
      description: Poll a submitted export job. 'ready' returns presigned download links for each Parquet part plus the manifest; 'pending' is still materialising; 'failed' includes an error. Scoped to the caller's API key.
      tags:
        - Equities
      parameters:
        - name: exportId
          in: path
          required: true
          schema:
            type: string
          description: The exportId returned by the submit call.
      responses:
        '200':
          description: Export status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      exportId:
                        type: string
                      status:
                        type: string
                        enum:
                          - ready
                          - pending
                          - failed
                      rows:
                        type: integer
                      requested:
                        type: integer
                        description: Count of explicitly-requested securities (absent for full-universe exports).
                      returned:
                        type: integer
                        description: Requested securities that returned >=1 row.
                      missing:
                        type: array
                        description: Requested securities that returned no rows.
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            reason:
                              type: string
                              enum:
                                - NO_DATA
                                - UNKNOWN_SECURITY
                      schema:
                        type: array
                        items:
                          type: string
                      expiresInSeconds:
                        type: integer
                        example: 3600
                      manifestUrl:
                        type: string
                      parts:
                        type: array
                        items:
                          type: object
                          properties:
                            metricName:
                              type: string
                            url:
                              type: string
                      error:
                        type: string
                        description: Present only when status=failed
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v2/estimates/consensus:
    get:
      operationId: estimates.consensus
      summary: Analyst Consensus Estimates
      description: 'Returns consensus EPS, EBITDA, and EBIT estimates across fiscal periods.


        Estimates are on the basis the covering analysts forecast, which for most companies is adjusted (non-GAAP): one-off items such as restructuring charges, impairments or tax effects are left out. EPS and net income therefore differ from the reported figures in `/v2/equities/income-statement` and from reported-basis series of other vendors. Tesla FY2025: consensus EPS 1.66 USD, reported 1.18 USD. SAP FY2024: consensus 4.44 EUR, reported 2.68 EUR.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Estimates
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EstimatePeriod'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - date: '2030-09-27'
                    symbol: AAPL
                    estimatedRevenueLow: 619792040000.0
                    estimatedRevenueHigh: 698463300000.0
                    estimatedRevenueAvg: 647707000000.0
                    estimatedEbitdaLow: 235875650000.0
                    estimatedEbitdaHigh: 272618100000.0
                    estimatedEbitdaAvg: 248913020000.0
                    estimatedEbitLow: 220967960000.0
                    estimatedEbitHigh: 257710390000.0
                    estimatedEbitAvg: 234005330000.0
                    estimatedNetIncomeLow: 182786620000.0
                    estimatedNetIncomeHigh: 213361690000.0
                    estimatedNetIncomeAvg: 193635610000.0
                    estimatedSgaExpenseLow: 39891337000.0
                    estimatedSgaExpenseHigh: 44954812000.0
                    estimatedSgaExpenseAvg: 41688015000.0
                    estimatedEpsLow: 12.182
                    estimatedEpsHigh: 14.2197
                    estimatedEpsAvg: 12.905
                    numberAnalystsEstimatedRevenue: null
                    numberAnalystsEstimatedEps: 15
                    currency: USD
                    fiscalYearEnd: '2030-09-27'
                    fiscalYear: 2030
                  - date: '2029-09-27'
                    symbol: AAPL
                    estimatedRevenueLow: 591422900000.0
                    estimatedRevenueHigh: 666493200000.0
                    estimatedRevenueAvg: 618060100000.0
                    estimatedEbitdaLow: 223721370000.0
                    estimatedEbitdaHigh: 258569800000.0
                    estimatedEbitdaAvg: 236086720000.0
                    estimatedEbitLow: 209645360000.0
                    estimatedEbitHigh: 244493800000.0
                    estimatedEbitAvg: 222010700000.0
                    estimatedNetIncomeLow: 173364580000.0
                    estimatedNetIncomeHigh: 202363550000.0
                    estimatedNetIncomeAvg: 183654330000.0
                    estimatedSgaExpenseLow: 38065430000.0
                    estimatedSgaExpenseHigh: 42897140000.0
                    estimatedSgaExpenseAvg: 39779873000.0
                    estimatedEpsLow: 11.554
                    estimatedEpsHigh: 13.4867
                    estimatedEpsAvg: 12.2398
                    numberAnalystsEstimatedRevenue: null
                    numberAnalystsEstimatedEps: 11
                    currency: USD
                    fiscalYearEnd: '2029-09-27'
                    fiscalYear: 2029
                meta:
                  parameters:
                    symbol: AAPL
                  time: 20
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/estimates/recommendations:
    get:
      operationId: estimates.recommendations
      summary: Analyst Recommendations
      description: 'Returns how many analysts currently hold each rating on the security,

        with the consensus label derived from that distribution.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Estimates
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RecommendationRecord'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  symbol: AAPL
                  strongBuy: 6
                  buy: 19
                  hold: 14
                  sell: 3
                  strongSell: 3
                  consensus: Hold
                meta:
                  parameters:
                    symbol: AAPL
                  time: 11
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/estimates/price-target:
    get:
      operationId: estimates.priceTarget
      summary: Price Target Consensus
      description: 'Returns analyst price target consensus including high, low, median and

        consensus values, and the currency they are quoted in.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Estimates
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PriceTargetConsensus'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  date: '2026-09-27'
                  symbol: AAPL
                  targetHigh: 400.0
                  targetLow: 245.0
                  targetConsensus: 342.13
                  targetMedian: 362.0
                  currency: USD
                meta:
                  parameters:
                    symbol: AAPL
                  time: 11
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/estimates/upgrades-downgrades:
    get:
      operationId: estimates.upgradesDowngrades
      summary: Upgrades & Downgrades
      description: 'Returns analyst rating changes (upgrades, downgrades, initiations).

        Each item is a weekly snapshot that lists every rating action known on

        its `date`, so the newest snapshot holds the full history. By default

        only the newest snapshot is returned; page back with `offset` or

        `cursor`, at most 10 snapshots per request.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Estimates
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UpgradeDowngradeRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - date: '2026-09-27'
                    symbol: AAPL
                    ratings:
                      - url: null
                        title: null
                        action: maintain
                        newGrade: Buy
                        previousGrade: Buy
                        publishedDate: '2026-09-23'
                        gradingCompany: B of A Securities
                        priceWhenPosted: null
                      - url: null
                        title: null
                        action: maintain
                        newGrade: Outperform
                        previousGrade: Outperform
                        publishedDate: '2026-09-18'
                        gradingCompany: Evercore ISI Group
                        priceWhenPosted: null
                meta:
                  page: 1
                  pageSize: 1
                  totalPages: 29
                  totalCount: 29
                  parameters:
                    limit: '1'
                    symbol: AAPL
                  time: 23
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 1
            minimum: 1
            maximum: 10
          description: Number of snapshots to return, newest first (default 1, max 10)
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/estimates/ai-estimates:
    post:
      operationId: estimates.aiEstimates
      summary: AI Estimates
      description: 'Bavest''s own AI estimates for a security across task types (regression,

        classification, sequence, hazard). Filter with `metrics` and `task_types`.

        Omit both to return everything.


        One prediction per metric, task type, target and frequency: the newest.

        A target whose period ended more than 120 days ago without an actual is

        left out, its figure is reported by then; earlier forecasts are on

        `/v2/estimates/ai-estimates-history`. Annual targets are calendar years

        (January to December) for every company, also where the fiscal year ends

        in another month: MSFT 2026 covers January to December 2026, not the

        fiscal year ending June 2026.'
      tags:
        - Estimates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - symbol
              properties:
                symbol:
                  type: string
                  description: Ticker symbol, ISIN, or CUSIP. Resolved server-side.
                  example: AAPL
                metrics:
                  type: array
                  description: Restrict to these metrics. Omit for all. Also accepts a comma-separated string.
                  items:
                    type: string
                  example:
                    - eps
                    - revenue
                task_types:
                  type: array
                  description: Restrict to these task types. Omit for all.
                  items:
                    type: string
                    enum:
                      - regression
                      - classification
                      - sequence
                      - hazard
                  example:
                    - regression
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PredictionsResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  meta:
                    as_of: '2026-05-20'
                    model_version: ai-eps-v1.4
                  predictions:
                    - symbol: AAPL
                      metric: eps
                      task_type: regression
                      target_date: '2026-09-30'
                      prediction_date: '2026-05-20'
                      model_version: ai-eps-v1.4
                      frequency: quarterly
                      prediction:
                        point: 2.41
                        lower: 2.18
                        upper: 2.65
                        components:
                          trend: 2.3
                          seasonal: 0.11
                      explainability:
                        top_features:
                          - name: revenue_ttm
                            shap: 0.42
                          - name: gross_margin
                            shap: 0.19
                meta:
                  parameters:
                    symbol: AAPL
                    metrics:
                      - eps
                    task_types:
                      - regression
                  time: 12
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/estimates/ai-estimates-history:
    get:
      operationId: estimates.aiEstimatesHistory
      summary: AI Estimates History
      description: 'Returns how an AI estimate for one metric evolved over time. Each

        `prediction_date` snapshot is a revision. Revisions are attributed to

        realized quarters, curated overrides, and the residual model re-estimate.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - Estimates
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PredictionHistoryResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  metric: revenue
                  targets:
                    - target_date: '2026-12-31'
                      fiscal_year: 2026
                      calendar_year: 2026
                      realized: false
                      current:
                        prediction_date: '2026-10-02'
                        model_version: revenue_lgb_purged_20261001
                        point: 507772463812.5977
                        lower: 466333211250.3338
                        upper: 549211716374.8616
                        realized: false
                        realized_sum: 220601000000.0
                        model_annual: 520839081098.4933
                        override_delta: 0.0
                        overrides: []
                      previous:
                        prediction_date: '2026-10-01'
                        model_version: revenue_lgb_purged_20261001
                        point: 507772463812.5977
                        lower: 466333211250.3338
                        upper: 549211716374.8616
                        realized: false
                        realized_sum: 220601000000.0
                        model_annual: 520839081098.4933
                        override_delta: 0.0
                        overrides: []
                      actual: null
                      revisions:
                        - from_date: '2026-05-22'
                          to_date: '2026-09-29'
                          from_point: 273563944311.7156
                          to_point: 474072675596.5948
                          delta: 200508731284.8792
                          drivers:
                            model: 200508731284.8792
                        - from_date: '2026-09-29'
                          to_date: '2026-09-30'
                          from_point: 474072675596.5948
                          to_point: 499387888309.2173
                          delta: 25315212712.6225
                          drivers:
                            realized: 220601000000.0
                            override: 0.0
                            model: -195285787287.3775
                      snapshots:
                        - prediction_date: '2026-05-22'
                          model_version: fmf-revenue-ensemble-v2
                          point: 273563944311.7156
                          lower: 173461359907.0481
                          upper: 373666528716.3831
                          realized: null
                          realized_sum: null
                          model_annual: null
                          override_delta: null
                          overrides: null
                        - prediction_date: '2026-09-29'
                          model_version: revenue_lgb_auto_20260526
                          point: 474072675596.5948
                          lower: 405663311114.142
                          upper: 542482040079.0475
                          realized: false
                          realized_sum: 0.0
                          model_annual: 474072675596.5948
                          override_delta: 0.0
                          overrides: []
                    - target_date: '2025-12-31'
                      fiscal_year: 2025
                      calendar_year: 2025
                      realized: false
                      current:
                        prediction_date: '2026-06-10'
                        model_version: revenue_lgb_auto_20260526
                        point: 438596944379.3873
                        lower: 417422737937.1071
                        upper: 459771150821.6675
                        realized: false
                        realized_sum: 291861000000.0
                        model_annual: 466321780248.617
                        override_delta: 0.0
                        overrides: []
                      previous:
                        prediction_date: '2026-06-09'
                        model_version: revenue_lgb_growth_20260527
                        point: 407304071346.03
                        lower: 390645471196.2831
                        upper: 423962671495.777
                        realized: false
                        realized_sum: 291861000000.0
                        model_annual: 366874106921.3515
                        override_delta: 0.0
                        overrides: []
                      actual: null
                      revisions:
                        - from_date: '2026-06-04'
                          to_date: '2026-06-05'
                          from_point: 407270732407.1996
                          to_point: 407270732407.1996
                          delta: 0.0
                          drivers:
                            realized: 0.0
                            override: 0.0
                            model: 0.0
                        - from_date: '2026-06-05'
                          to_date: '2026-06-06'
                          from_point: 407270732407.1996
                          to_point: 407270732407.1996
                          delta: 0.0
                          drivers:
                            realized: 0.0
                            override: 0.0
                            model: 0.0
                      snapshots:
                        - prediction_date: '2026-06-04'
                          model_version: revenue_lgb_growth_20260527
                          point: 407270732407.1996
                          lower: 390616943113.9633
                          upper: 423924521700.436
                          realized: false
                          realized_sum: 291861000000.0
                          model_annual: 366768156921.3515
                          override_delta: 0.0
                          overrides: []
                        - prediction_date: '2026-06-05'
                          model_version: revenue_lgb_growth_20260527
                          point: 407270732407.1996
                          lower: 390616943113.9633
                          upper: 423924521700.436
                          realized: false
                          realized_sum: 291861000000.0
                          model_annual: 366768156921.3515
                          override_delta: 0.0
                          overrides: []
                meta:
                  parameters:
                    metric: revenue
                    symbol: AAPL
                  time: 2524
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - name: metric
          in: query
          required: true
          description: Single metric to trace, e.g. revenue, eps, ebitda.
          schema:
            type: string
            example: revenue
        - name: fiscal_year
          in: query
          required: false
          description: 'Pin to one target fiscal year (target_date = Dec-31 of that year). Omit for all. Example when explicitly filtering: `2026`.'
          schema:
            type: integer
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/category:
    get:
      operationId: etfs.category
      summary: ETF Category
      description: Returns ETF classification and categorization including asset class, focus, and niche.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ETFCategory'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  assetClass: Equity
                  category: Global Equity
                  focus: Broad Market
                  niche: MSCI World Index Exposure
                  index: MSCI World
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 25
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/countries:
    get:
      operationId: etfs.countries
      summary: ETF Country Exposure
      description: Returns geographic allocation percentages.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      atDate:
                        type: string
                        format: date
                        description: Observation date for the exposure data
                      countryExposure:
                        type: array
                        items:
                          $ref: '#/components/schemas/ETFCountryExposure'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  atDate: '2026-10-02'
                  countryExposure:
                    - country: United States
                      exposure: 72.68
                      synthetic: false
                    - country: Japan
                      exposure: 5.91
                      synthetic: false
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 192
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
        - $ref: '#/components/parameters/etfViewQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/documents/catalog:
    get:
      operationId: etfs.documentCatalog
      summary: ETF Documents Catalog
      description: Returns a paginated catalog of all available ETF documents (KID/KIID) for a given language. Use the download_path to fetch each document via /v2/etfs/kid.
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ETFDocumentCatalogItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - isin: ABA1285663C9
                    language: en
                    type: KID
                    download_path: /v2/etfs/kid?isin=ABA1285663C9&language=en&type=KID
                  - isin: ADEB985A5832
                    language: en
                    type: KID
                    download_path: /v2/etfs/kid?isin=ADEB985A5832&language=en&type=KID
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 137
                  totalCount: 13664
                  parameters:
                    language: en
                    limit: '100'
                  time: 154
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - name: language
          in: query
          required: true
          schema:
            type: string
            example: en
          description: ISO 639-1 language code (e.g. en, de, fr)
        - name: isin
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
            minLength: 12
            maxLength: 12
          description: Only this fund's documents (e.g., `IE00B4L5Y983`). Omit for the whole catalog. Provide at most one of isin or symbol.
        - name: symbol
          in: query
          required: false
          schema:
            type: string
          description: Only the documents of this listing's fund, resolved to its ISIN (e.g., `IWDA.AS`). An unknown symbol is 404. Omit for the whole catalog.
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - KID
              - KIID
          description: Filter by document type. Omit to return both KID and KIID.
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/etfs/fees:
    get:
      operationId: etfs.fees
      summary: ETF Fees
      description: Returns ETF fee and expense information including management fee and expense ratios.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ETFFees'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  managementFee: 0.2
                  performanceFee: null
                  netExpenseRatio: 0.2
                  totalExpenseRatio: 0.2
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 33
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/holdings:
    get:
      operationId: etfs.holdings
      summary: ETF Holdings
      description: Returns all holdings with weights, values, and share counts. Swaps, futures, Treasury bills, money market funds and cash are rows of their own (`holdingType`); `view` picks market-value weights (`display`, default) or the issuer's exposure weights (`raw`).


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Holdings for the requested page.
                    items:
                      $ref: '#/components/schemas/HoldingRecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - name: NVIDIA CORP
                    percent: 5.7488
                    value: 8712724624.12
                    isin: US67066G1040
                    symbol: NVDA
                    cusip: null
                    share: 38346572.0
                  - name: APPLE INC
                    percent: 5.3245
                    value: 8069636917.8
                    isin: US0378331005
                    symbol: AAPL
                    cusip: null
                    share: 24497987.0
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 13
                  totalCount: 1265
                  parameters:
                    isin: IE00B4L5Y983
                    limit: '100'
                  time: 48
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
        - $ref: '#/components/parameters/holdingsViewQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/holdings/top:
    get:
      operationId: etfs.topHoldings
      summary: ETF Holdings Top
      description: Returns top 10 holdings by weight, in the chosen `view` (`display` by market value, default; `raw` by absolute exposure weight).


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      symbol:
                        type: string
                        nullable: true
                        description: Resolved ETF ticker, echoed from the lookup.
                      atDate:
                        type: string
                        format: date
                      holdings:
                        type: array
                        items:
                          $ref: '#/components/schemas/HoldingRecord'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  holdings:
                    - symbol: null
                      cusip: null
                      name: NVIDIA
                      share: null
                      percent: 5.6408
                      value: null
                      isin: null
                    - symbol: null
                      cusip: null
                      name: APPLE
                      share: null
                      percent: 5.461
                      value: null
                      isin: null
                  atDate: '2026-09-28'
                  symbol: null
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 125
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
        - $ref: '#/components/parameters/holdingsViewQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/kid:
    get:
      operationId: etfs.kidDocument
      summary: ETF KID Document
      description: Returns the Key Information Document (KID) as a PDF file.
      tags:
        - ETFs
      responses:
        '200':
          description: KID document (application/pdf)
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: isin
          in: query
          required: true
          schema:
            type: string
            example: IE00B4L5Y983
          description: ETF ISIN code (required for KID endpoints)
        - name: language
          in: query
          schema:
            type: string
            default: en
          description: 'Language code (ISO 639-1). `lang` is accepted as an alias. Example when explicitly filtering: `en`.'
        - name: type
          in: query
          schema:
            type: string
            enum:
              - KID
              - KIID
          description: 'Which document to return. Omit it and the endpoint returns the PRIIPs KID, falling back to the UCITS KIID when no KID is held for that language. Set it to fetch one specific document -- in particular a KIID for an ISIN that also has a KID in the same language, which is otherwise unreachable even though /v2/etfs/documents/catalog lists it. Example when explicitly filtering: `KIID`.'
  /v2/etfs/kid/languages:
    get:
      operationId: etfs.kidLanguages
      summary: ETF KID Languages
      description: Returns available language codes for a specific ETF's KID document.
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      languages:
                        type: array
                        items:
                          type: string
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  languages:
                    - de
                    - en
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - name: isin
          in: query
          required: true
          schema:
            type: string
            example: IE00B4L5Y983
          description: ETF ISIN code (required for KID endpoints)
  /v2/etfs/list:
    get:
      operationId: etfs.list
      summary: ETF List
      description: 'Returns a paginated list of all ETF, ETP, and ETN listings. The list is listing-level: one row per exchange listing, so the same ISIN can appear multiple times. `isin` is guaranteed ISO-6166-shaped; `name` may be null when no name has been resolved yet.'
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecurityListItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - isin: ZAE000273165
                    symbol: CSPROP.JO
                    name: 10X South African Property Income ETF
                    country: ZA
                    exchange: Johannesburg Stock Exchange
                    exchangeCode: JNB
                    sector: Financial Services
                  - isin: ZAE000268694
                    symbol: CSP500.JO
                    name: 10X S&P 500 ETF
                    country: ZA
                    exchange: Johannesburg Stock Exchange
                    exchangeCode: JNB
                    sector: Financial Services
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 354
                  totalCount: 35383
                  parameters:
                    limit: '100'
                  time: 5
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
        - name: exchangeCode
          in: query
          required: false
          schema:
            type: string
          description: 'Filter by exchange short code (e.g. NASDAQ, NYSE) Example when explicitly filtering: `NASDAQ`.'
  /v2/etfs/metrics:
    get:
      operationId: etfs.metrics
      summary: ETF Metrics
      description: "Returns a paginated list of all ETF metrics — performance, risk, volatility,

        and fund characteristics — with full lineage/traceability.


        **Metric groups:**

        - **Returns:** 1M, 3M, YTD, 1Y, 3Y, 5Y, 10Y; annualized 5Y; since inception

        \  (cumulative and annualized). Returns are total returns: distributions are added back

        \  to the closes (an accumulating share class is used as quoted).

        - **Risk (security & category):** beta, alpha, sharpe ratio, treynor ratio,

        \  R-squared, standard deviation, mean annual return (1Y/3Y/5Y/10Y)

        - **Volatility:** YTD, 1Y, 3Y, 5Y, 10Y

        - **Risk indicators:** SRI (price-based, 1-7), SRRI (document-based, 1-7)

        - **Fund:** tracking error, net management fee

        - **Dividends:** dividend_yield (trailing 12-month distributions / latest close,

        \  percent; 0.0 for accumulating share classes)


        Pass `trace=true` to include computation lineage (formula, inputs, explanation)

        for each metric.



        Check each metric's `date` for freshness. `latestDate` is the newest date across metrics and does not mean every metric (including AUM) is current.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`)."
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      latestDate:
                        type: string
                        format: date
                        nullable: true
                        description: Most recent observation date across all metrics
                        example: '2026-10-02'
                      metrics:
                        type: array
                        items:
                          $ref: '#/components/schemas/ETFMetricItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  latestDate: '2026-10-02'
                  metrics:
                    - metricId: aum
                      metricName: aum
                      value: 147022599924.06
                      date: '2026-10-01'
                      valid: true
                      unit: CURRENCY
                      currency: USD
                    - metricId: nav
                      metricName: nav
                      value: 145.4398
                      date: '2026-10-01'
                      valid: true
                      unit: CURRENCY
                      currency: USD
                meta:
                  page: 1
                  pageSize: 50
                  totalPages: 3
                  totalCount: 101
                  parameters:
                    isin: IE00B4L5Y983
                    limit: '50'
                  time: 68
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
        - name: fields
          in: query
          required: false
          schema:
            type: string
          description: 'Comma-separated list of metric names to include in the response. Valid names are served by `/v2/etfs/metrics/names`. Example when explicitly filtering: `nav,aum,expense_ratio`.'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 50
            minimum: 1
            maximum: 200
          description: Maximum number of metrics to return per page (default 50, max 200)
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
        - name: trace
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include computation lineage (formula, inputs, explanation) for each metric
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/profile:
    get:
      operationId: etfs.profile
      summary: ETF Profile
      description: 'Returns ETF identity and classification.


        > Fees, risk metrics, structure and NAV live in dedicated resources: `/v2/etfs/fees`, `/v2/etfs/risk`, `/v2/etfs/structure`, `/v2/securities/nav`, `/v2/etfs/metrics`. Holdings count is `meta.totalCount` on `/v2/etfs/holdings`.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).'
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ETFProfile'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  symbol: IWDA.L
                  isin: IE00B4L5Y983
                  cusip: ''
                  name: iShares Core MSCI World UCITS ETF USD (Acc)
                  description: With the iShares Core MSCI World UCITS ETF (Acc), investors can participate in the performance of currently over 1,500 large and medium-sized companies from 23 developed markets. The ETF thus enables access to an internationally diversified market segment.
                  assetClass: Equity
                  domicile: IE
                  etfCompany: iShares
                  inceptionDate: '2009-09-25'
                  website: ''
                  etfCategory: Global Equity
                  etfFocus: Broad Market
                  etfNiche: MSCI World Index Exposure
                  indice: MSCI World
                  distributionPolicy: Accumulating
                  replicationMethod: physical
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 28
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/risk:
    get:
      operationId: etfs.risk
      summary: ETF Risk
      description: Returns risk metrics including beta, SRI/SRRI, tracking error, and volatility.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ETFRisk'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  symbol: IWDA.L
                  betaOneYear: -0.0001
                  betaThreeYears: 0.0007
                  betaFiveYears: 0.0019
                  sri: 4
                  srri: 6
                  trackingError: 0.0532
                  volatility: 0.1101
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 35
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/sectors:
    get:
      operationId: etfs.sectors
      summary: ETF Sector Exposure
      description: Returns sector allocation percentages.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      atDate:
                        type: string
                        format: date
                        description: Observation date for the exposure data
                      sectorExposure:
                        type: array
                        items:
                          $ref: '#/components/schemas/ETFSectorExposure'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  sectorExposure:
                    - sector: Information Technology
                      synthetic: false
                      exposure: 31.39
                    - sector: Financials
                      synthetic: false
                      exposure: 15.81
                  atDate: '2026-09-30'
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 679
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
        - $ref: '#/components/parameters/etfViewQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/sectors/top:
    get:
      operationId: etfs.topSectors
      summary: ETF Sectors Top
      description: Returns top sectors by allocation.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      atDate:
                        type: string
                        format: date
                        description: Observation date for the exposure data
                      sectorExposure:
                        type: array
                        items:
                          $ref: '#/components/schemas/ETFSectorExposure'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  sectorExposure:
                    - sector: Information Technology
                      synthetic: false
                      exposure: 31.39
                    - sector: Financials
                      synthetic: false
                      exposure: 15.81
                  atDate: '2026-09-30'
                meta:
                  page: 1
                  pageSize: 10
                  totalPages: 2
                  totalCount: 13
                  parameters:
                    isin: IE00B4L5Y983
                  time: 385
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/metrics/names:
    get:
      operationId: etfs.metricNames
      summary: ETF Metric Names
      description: 'Returns every metric name available on `/v2/etfs/metrics`, with the unit

        and a description for each name.


        Use these names with the `fields` parameter of `/v2/etfs/metrics`. The

        vocabulary is versioned with the API. New metric names may be added over

        time and additions are backward compatible.


        No ETF identifier is required.'
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Total number of registered metric names
                        example: 92
                      metrics:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Canonical metric name (snake_case)
                              example: beta_one_year_security
                            unit:
                              type: string
                              description: Unit of measurement (MetricUnitModel value)
                              enum:
                                - CURRENCY
                                - NUMERIC
                                - PERCENTAGE
                                - RATIO
                                - DATE
                                - BOOLEAN
                                - YEARS
                              example: RATIO
                            description:
                              type: string
                              description: Human-readable description of the metric
                              example: 1-year beta of the fund versus S&P 500
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  count: 104
                  metrics:
                    - name: alpha_five_years_category
                      unit: RATIO
                      description: 5-year Jensen's alpha of the fund's category
                    - name: alpha_five_years_security
                      unit: RATIO
                      description: 5-year Jensen's alpha of the fund
                meta:
                  time: 57
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/etfs/countries/top:
    get:
      operationId: etfs.topCountries
      summary: ETF Countries Top
      description: Returns top countries by allocation.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      atDate:
                        type: string
                        format: date
                        description: Observation date for the exposure data
                      countryExposure:
                        type: array
                        items:
                          $ref: '#/components/schemas/ETFCountryExposure'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  countryExposure:
                    - country: United States
                      exposure: 72.68
                      synthetic: false
                    - country: Japan
                      exposure: 5.91
                      synthetic: false
                  atDate: '2026-10-02'
                meta:
                  page: 1
                  pageSize: 10
                  totalPages: 2
                  totalCount: 11
                  parameters:
                    isin: IE00B4L5Y983
                  time: 3736
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/countries/list:
    get:
      operationId: etfs.countryList
      summary: ETF Country List
      description: "Returns the canonical set of values the `country` field of ETF geographic

        allocation (`/v2/etfs/countries`) can take.


        Every `country` value served by the API appears in this list. The list is

        complete and authoritative. Each entry is tagged by `type`:


        - `country`: ISO 3166 country or territory, including common aliases

        - `region`: multi-country grouping such as \"Europe\" or \"Emerging Markets\"

        - `supranational`: non-sovereign issuer bucket such as \"Supranational\" or

        \  \"European Union\", common in bond ETFs (World Bank, EIB, EU)

        - `other`: non-geographic values such as \"Cash\", \"Other\", \"Unknown\", \"N/A\"


        No ETF identifier is required."
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Total number of country values in the catalog
                        example: 293
                      countries:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Country-allocation value
                              example: United States
                            type:
                              type: string
                              description: Value category
                              enum:
                                - country
                                - region
                                - supranational
                                - other
                              example: country
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  count: 301
                  countries:
                    - name: ASEAN
                      type: region
                    - name: Afghanistan
                      type: country
                meta:
                  time: 462
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/etfs/structure:
    get:
      operationId: etfs.structure
      summary: ETF Structure
      description: Returns ETF structural classification including leverage, complexity, and benchmark status.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - ETFs
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ETFStructure'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  type: ETF
                  isBenchmark: false
                  isIndexTracked: true
                  isLeveraged: false
                  isComplex: false
                  isStructured: false
                meta:
                  parameters:
                    isin: IE00B4L5Y983
                  time: 28
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/etfs/exports:
    post:
      operationId: etfs.exportSubmit
      summary: Submit ETF Data Export
      description: 'Submit an asynchronous export job for this account''s ETF data. `dataset` selects the source: `metrics` (default), `countries`, `sectors`, or `holdings`. Choose symbols and/or isins (at least one, at most 100 together) and a from/to window (`metrics` also accepts a metric-name list); the Parquet export is prepared asynchronously, then poll GET /etfs/exports/{exportId} for signed download links. symbols and isins union. A request with neither is a 400. Scoped to the caller''s API key.'
      tags:
        - ETFs
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                dataset:
                  type: string
                  enum:
                    - metrics
                    - countries
                    - sectors
                    - holdings
                  default: metrics
                  description: Which ETF dataset to export.
                metrics:
                  type: array
                  items:
                    type: string
                  description: Metric-name filter (dataset=metrics only).
                symbols:
                  type: array
                  items:
                    type: string
                isins:
                  type: array
                  items:
                    type: string
                from:
                  type: string
                  format: date
                to:
                  type: string
                  format: date
      responses:
        '200':
          description: Job accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      exportId:
                        type: string
                      assetClass:
                        type: string
                        example: etf
                      status:
                        type: string
                        example: pending
                      poll:
                        type: string
                        description: Poll this path for status and links
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v2/etfs/exports/{exportId}:
    get:
      operationId: etfs.exportStatus
      summary: ETF Export Status
      description: Poll a submitted export job. 'ready' returns presigned download links for each Parquet part plus the manifest; 'pending' is still materialising; 'failed' includes an error. Scoped to the caller's API key.
      tags:
        - ETFs
      parameters:
        - name: exportId
          in: path
          required: true
          schema:
            type: string
          description: The exportId returned by the submit call.
      responses:
        '200':
          description: Export status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      exportId:
                        type: string
                      status:
                        type: string
                        enum:
                          - ready
                          - pending
                          - failed
                      rows:
                        type: integer
                      requested:
                        type: integer
                        description: Count of explicitly-requested securities (absent for full-universe exports).
                      returned:
                        type: integer
                        description: Requested securities that returned >=1 row.
                      missing:
                        type: array
                        description: Requested securities that returned no rows.
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            reason:
                              type: string
                              enum:
                                - NO_DATA
                                - UNKNOWN_SECURITY
                      schema:
                        type: array
                        items:
                          type: string
                      expiresInSeconds:
                        type: integer
                        example: 3600
                      manifestUrl:
                        type: string
                      parts:
                        type: array
                        items:
                          type: object
                          properties:
                            metricName:
                              type: string
                            url:
                              type: string
                      error:
                        type: string
                        description: Present only when status=failed
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v2/etfs/asset-class-breakdown:
    get:
      operationId: etfs.asset_class_breakdown
      summary: ETF Asset Class Breakdown
      description: Returns asset-class allocation percentages based on holdings, including recursive look-through of underlying funds and ETFs. Preserves signed weights and reports missing or unclassified exposure as unknown.
      tags:
        - ETFs
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/etfSymbolQuery'
        - $ref: '#/components/parameters/etfIsinQuery'
        - $ref: '#/components/parameters/cusipQuery'
      responses:
        '200':
          description: Holdings-based allocation including explicit unknown weight.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                      - assetClassBreakdown
                    properties:
                      atDate:
                        type: string
                        format: date
                        nullable: true
                      oldestHoldingsDate:
                        type: string
                        format: date
                        nullable: true
                      assetClassBreakdown:
                        type: array
                        items:
                          type: object
                          required:
                            - assetClass
                            - percent
                          properties:
                            assetClass:
                              type: string
                              enum:
                                - equity
                                - fixed_income
                                - cash_money_market
                                - commodities
                                - crypto
                                - other
                                - unknown
                            percent:
                              type: number
                            longPercent:
                              type: number
                              minimum: 0
                            shortPercent:
                              type: number
                              minimum: 0
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  atDate: '2026-09-30'
                  oldestHoldingsDate: '2026-08-31'
                  assetClassBreakdown:
                    - assetClass: equity
                      percent: 72
                      longPercent: 72
                      shortPercent: 0
                    - assetClass: fixed_income
                      percent: 15
                      longPercent: 15
                      shortPercent: 0
                    - assetClass: cash_money_market
                      percent: 0
                      longPercent: 0
                      shortPercent: 0
                    - assetClass: commodities
                      percent: 0
                      longPercent: 0
                      shortPercent: 0
                    - assetClass: crypto
                      percent: 0
                      longPercent: 0
                      shortPercent: 0
                    - assetClass: other
                      percent: 0
                      longPercent: 0
                      shortPercent: 0
                    - assetClass: unknown
                      percent: 13
                      longPercent: 13
                      shortPercent: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/filings/earnings:
    get:
      operationId: filings.earnings
      summary: Earnings Release Filings
      description: 'Real-time feed of SEC 8-K earnings-release filings (item 2.02). Each event first appears at `stage=announced`

        (lowest latency, minimal fields — typically seconds after the filing

        hits EDGAR) and is updated to `stage=enriched` once additional filing details are available.


        Omit `symbol`/`isin`/`cusip` for the full firehose across all

        companies. `from`/`to` filter on `filed_at`. For low-latency polling,

        use `updated_since` instead of `from`/`to`: it switches the sort order

        to `updated_at` ascending so a cursor never skips a row that was

        updated between polls (e.g. an `announced` row that became

        `enriched`). Ordered `filed_at DESC` by default, `updated_at ASC` when

        `updated_since` is set.'
      tags:
        - Filings
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarningsReleaseList'
              example:
                data:
                  - event_type: earnings_release
                    source: sec_edgar
                    form_type: 8-K
                    is_amendment: false
                    amends_accession_number: null
                    items:
                      - '2.02'
                      - '9.01'
                    identifiers:
                      symbol: TSLA
                      isin: US88160R1014
                      cusip: null
                      cik: 1318605
                      lei: null
                    company_name: Tesla, Inc.
                    accession_number: 0001628280-26-064366
                    filed_at: '2026-10-02T13:04:26+00:00'
                    updated_at: '2026-10-02T14:00:58.860270+00:00'
                    report_date: '2026-10-02'
                    headline: Document
                    documents:
                      filing_index: https://www.sec.gov/Archives/edgar/data/1318605/000162828026064366/0001628280-26-064366-index.htm
                      press_release: https://www.sec.gov/Archives/edgar/data/1318605/000162828026064366/exhibit991111111.htm
                      exhibits:
                        - url: https://www.sec.gov/ix?doc=/Archives/edgar/data/1318605/000162828026064366/tsla-20261002.htm
                          type: 8-K
                          description: 8-K
                        - url: https://www.sec.gov/Archives/edgar/data/1318605/000162828026064366/exhibit991111111.htm
                          type: EX-99.1
                          description: EX-99.1
                    period:
                      fiscal_year: null
                      fiscal_quarter: null
                      period_end: null
                  - event_type: earnings_release
                    source: sec_edgar
                    form_type: 8-K
                    is_amendment: false
                    amends_accession_number: null
                    items:
                      - '2.02'
                      - '9.01'
                    identifiers:
                      symbol: TMQ
                      isin: CA89621C1059
                      cusip: null
                      cik: 1543418
                      lei: null
                    company_name: Trilogy Metals Inc.
                    accession_number: 0001279569-26-000946
                    filed_at: '2026-10-02T12:39:09+00:00'
                    updated_at: '2026-10-02T13:00:50.371646+00:00'
                    report_date: '2026-10-02'
                    headline: Exhibit 99.1
                    documents:
                      filing_index: https://www.sec.gov/Archives/edgar/data/1543418/000127956926000946/0001279569-26-000946-index.htm
                      press_release: https://www.sec.gov/Archives/edgar/data/1543418/000127956926000946/ex991.htm
                      exhibits:
                        - url: https://www.sec.gov/ix?doc=/Archives/edgar/data/1543418/000127956926000946/form8k.htm
                          type: 8-K
                          description: ''
                        - url: https://www.sec.gov/Archives/edgar/data/1543418/000127956926000946/ex991.htm
                          type: EX-99.1
                          description: NEWS RELEASE DATED OCTOBER 2, 2026
                    period:
                      fiscal_year: null
                      fiscal_quarter: null
                      period_end: '2026-08-31'
                meta:
                  pageSize: 50
                  hasMore: true
                  nextCursor: eyJmaWxlZF9hdCI6ICIyMDI2LTA5LTI0VDIwOjA1OjI0KzAwOjAwIiwgImFjY2Vzc2lvbl9udW1iZXIiOiAiMDAwMTQ5MzE1Mi0yNi0wNDQxNDUifQ==
                  parameters:
                    limit: '50'
                  time: 3627
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolFilterQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/cusipQuery'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/updatedSinceQuery'
        - $ref: '#/components/parameters/filingsLimitQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/forex/candles/{pair}:
    get:
      operationId: forex.candles
      summary: Forex OHLCV Candles
      description: Returns OHLCV candlestick data for a currency pair.
      tags:
        - Forex
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ForexCandle'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - price: 1.16164
                    change: -0.00061
                    changesPercentage: -0.05248441
                    timestamp: '2026-09-01T00:00:57'
                    dayLow: 1.16132
                    dayHigh: 1.16225
                    open: 1.16212
                    previousClose: 1.16225
                  - price: 1.16238
                    change: 0.00013
                    changesPercentage: 0.0111852
                    timestamp: '2026-09-01T00:30:04'
                    dayLow: 1.16132
                    dayHigh: 1.16279
                    open: 1.16212
                    previousClose: 1.16225
                meta:
                  parameters:
                    pair: EURUSD
                    from: '2026-09-01'
                    resolution: D
                    to: '2026-09-30'
                  time: 3467
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/pairPath'
        - $ref: '#/components/parameters/resolutionQuery'
        - $ref: '#/components/parameters/fromQueryRequired'
        - $ref: '#/components/parameters/toQueryRequired'
  /v2/forex/quote/{pair}:
    get:
      operationId: forex.quote
      summary: Forex Quote
      description: Returns real-time forex pair quote.
      tags:
        - Forex
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ForexQuote'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  symbol: EURUSD
                  price: 1.1275
                  change: 0.0030201
                  changesPercentage: 0.26858
                  open: 1.12435
                  previousClose: 1.12448
                  dayHigh: 1.12758
                  dayLow: 1.12246
                  timestamp: '2026-10-02T14:00:18'
                meta:
                  parameters:
                    pair: EURUSD
                  time: 16
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/pairPath'
  /v2/funds/countries/{isin}:
    get:
      operationId: funds.countries
      summary: Fund Country Allocation
      description: Returns geographic exposure percentages.
      tags:
        - Funds
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      atDate:
                        type: string
                        format: date
                        description: Observation date for the exposure data
                      countryExposure:
                        type: array
                        items:
                          $ref: '#/components/schemas/CountryExposure'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  countryExposure:
                    - country: Cash
                      exposure: 0.5
                    - country: Netherlands
                      exposure: 1.5
                  atDate: '2026-08-31'
                meta:
                  parameters:
                    isin: DE0009848119
                  time: 33
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/fundIsinPath'
  /v2/funds/holdings/{isin}:
    get:
      operationId: funds.holdings
      summary: Fund Holdings
      description: Returns top holdings with exposure percentages.
      tags:
        - Funds
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      atDate:
                        type: string
                        format: date
                        description: Observation date for the holdings data
                      holdings:
                        type: array
                        items:
                          $ref: '#/components/schemas/FundHolding'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  holdings:
                    - name: Agnico Eagle Mines
                      exposure: 3.7
                    - name: Taiwan Semiconduct. Manufact. Co
                      exposure: 3.3
                  atDate: '2026-08-31'
                meta:
                  parameters:
                    isin: DE0009848119
                  time: 27
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/fundIsinPath'
  /v2/funds/metrics:
    get:
      operationId: funds.metrics
      summary: Fund Metrics
      description: "Returns all metrics for a fund in a single paginated response, with the

        latest observation per metric name.


        Metric groups:

        - NAV: latest net asset value per share in the quoted currency

        - AUM: total fund assets under management, aggregated across all share

        \  classes of the fund

        - Cumulative returns: YTD, 1M, 3M, 6M, 1Y, 3Y, 5Y, 10Y and since

        \  inception, in percent

        - Annualized returns: 3Y, 5Y, 10Y and since inception, in percent

        - Calendar year returns: `calendar_year_return_YYYY`, in percent

        - Risk and cost metrics: volatility, Sharpe ratio, beta, alpha, information

        \  ratio, tracking error, max drawdown, TER, ongoing charges and SRI


        Coverage varies by metric and fund. NAV and AUM cover most of the fund

        universe. Performance returns are backfilled progressively and may be

        unavailable for individual funds. The `date` field of each item states

        the observation date of that value.


        Use `fields` to select specific metrics by `metricId` or `metricName`.

        The endpoint `/v2/funds/metrics/names` returns all valid metric names."
      tags:
        - Funds
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      latestDate:
                        type: string
                        format: date
                        nullable: true
                        description: Most recent observation date across all metrics
                        example: '2026-08-31'
                      metrics:
                        type: array
                        items:
                          $ref: '#/components/schemas/FundMetricItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  latestDate: '2026-08-31'
                  metrics:
                    - metricId: aum
                      metricName: aum
                      value: 24552928300.0
                      date: '2026-07-31'
                      valid: true
                      unit: CURRENCY
                      currency: EUR
                    - metricId: nav
                      metricName: nav
                      value: 176.61
                      date: '2026-08-31'
                      valid: true
                      unit: CURRENCY
                      currency: EUR
                meta:
                  page: 1
                  pageSize: 50
                  totalPages: 1
                  totalCount: 49
                  parameters:
                    isin: DE0009848119
                    limit: '50'
                  time: 1177
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - name: isin
          in: query
          required: true
          schema:
            type: string
            example: DE0009848119
            pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
            minLength: 12
            maxLength: 12
          description: Fund ISIN code (e.g., `DE0009848119`)
        - name: fields
          in: query
          required: false
          schema:
            type: string
          description: 'Comma-separated list of metric names to include in the response. Valid names are served by `/v2/funds/metrics/names`. Example when explicitly filtering: `nav,aum,cumulative_return_5y,annualized_return_5y`.'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 50
            minimum: 1
            maximum: 200
          description: Maximum number of metrics to return per page (default 50, max 200)
        - $ref: '#/components/parameters/offsetQuery'
  /v2/funds/metrics/names:
    get:
      operationId: funds.metricNames
      summary: Fund Metric Names
      description: 'Returns every metric name available on `/v2/funds/metrics`, with the

        unit and a description for each name. Metric families such as calendar

        year returns are returned as name patterns. Any name that matches a

        listed pattern is a valid metric name, for example

        `calendar_year_return_2025`.


        Use these names with the `fields` parameter of `/v2/funds/metrics`. The

        vocabulary is versioned with the API. New metric names may be added over

        time and additions are backward compatible.


        No fund identifier is required.'
      tags:
        - Funds
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Number of exact metric names (name-pattern families are listed separately and not included in the count)
                        example: 51
                      metrics:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Canonical metric name (snake_case)
                              example: cumulative_return_1y
                            unit:
                              type: string
                              description: Unit of measurement (MetricUnitModel value)
                              enum:
                                - CURRENCY
                                - PERCENTAGE
                                - RATIO
                                - NUMERIC
                              example: PERCENTAGE
                            description:
                              type: string
                              description: Human-readable description of the metric
                              example: Total return over the trailing 1-year window
                      patterns:
                        type: array
                        description: Metric-name families accepted in addition to the exact names
                        items:
                          type: object
                          properties:
                            pattern:
                              type: string
                              description: Regular expression the metric name must match
                              example: ^calendar_year_return_(19|20)[0-9]{2}$
                            unit:
                              type: string
                              description: Unit of measurement (MetricUnitModel value)
                              enum:
                                - CURRENCY
                                - PERCENTAGE
                                - RATIO
                                - NUMERIC
                              example: PERCENTAGE
                            description:
                              type: string
                              description: Human-readable description of the metric family
                              example: Calendar-year total return; the year is part of the metric name
                  meta:
                    type: object
                    description: Response envelope metadata.
                    properties:
                      time:
                        type: integer
                        description: Server-side processing time in milliseconds
                        example: 17
                      parameters:
                        type: object
                        additionalProperties: true
                        description: Echo of the request parameters the endpoint resolved
                        example: {}
              example:
                data:
                  count: 52
                  metrics:
                    - name: alpha_10y
                      unit: RATIO
                      description: Alpha vs. the peergroup benchmark, trailing 10 years (EUR basis)
                    - name: alpha_1y
                      unit: RATIO
                      description: Alpha vs. the peergroup benchmark, trailing 1 year (EUR basis)
                  patterns:
                    - pattern: ^calendar_year_return_(19|20)[0-9]{2}$
                      unit: PERCENTAGE
                      description: Calendar-year total return; the year is part of the metric name
                meta:
                  time: 298
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/funds/profile/{isin}:
    get:
      operationId: funds.profile
      summary: Fund Profile
      description: Returns mutual fund identity and classification.
      tags:
        - Funds
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      isin:
                        type: string
                        description: Fund ISIN code
                        example: DE0009848119
                      name:
                        type: string
                        description: Fund name
                      fundCompany:
                        type: string
                        description: Fund management company
                      description:
                        type: string
                        description: Fund investment objective description
                      inceptionDate:
                        type: string
                        format: date
                        nullable: true
                        description: Fund inception date (yyyy-mm-dd)
                        example: '2003-04-28'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  isin: DE0009848119
                  name: DWS Top Dividende LD
                  description: Der Fonds bietet eine Aktienanlage mit Chance auf laufenden Ertrag. Das Management investiert weltweit in Aktien, vorrangig hochkapitalisierte Werte, die eine höhere Dividendenrendite als der Marktdurchschnitt erwarten lassen. Seit Auflegung liegt die Dividendenrendite des Fondsportfolios bei durchschnittlich 4,0 bis 4,5 Prozent. Das bleibt auch in Zukunft Orientierungsgröße.
                  fundCompany: DWS Investment GmbH
                  inceptionDate: '2003-04-28'
                meta:
                  parameters:
                    isin: DE0009848119
                  time: 52
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/fundIsinPath'
  /v2/funds/sectors/{isin}:
    get:
      operationId: funds.sectors
      summary: Fund Sector Allocation
      description: Returns sector exposure percentages.
      tags:
        - Funds
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      atDate:
                        type: string
                        format: date
                        description: Observation date for the exposure data
                      sectorExposure:
                        type: array
                        items:
                          $ref: '#/components/schemas/SectorExposure'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  sectorExposure:
                    - sector: Communication Services
                      exposure: 2.53
                    - sector: Financials
                      exposure: 17.2
                  atDate: '2026-10-01'
                meta:
                  parameters:
                    isin: DE0009848119
                  time: 22
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/fundIsinPath'
  /v2/funds/list:
    get:
      operationId: funds.list
      summary: Fund List
      description: Returns a paginated list of all mutual funds.
      tags:
        - Funds
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FundListItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - isin: DE000DNA10Q7
                    name: 10XDNA - Disruptive Technologies ex Crypto I-II
                    fundCompany: AXXION S.A.
                  - isin: DE000DNA10R5
                    name: 10XDNA - Disruptive Technologies ex Crypto R
                    fundCompany: AXXION S.A.
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 333
                  totalCount: 33262
                  nextCursor: eyJuYW1lIjogIkFCIEZDUCBJIC0gQW1lcmljYW4gSW5jb21lIFBvcnRmb2xpbyBBIiwgImlzaW4iOiAiTFUwMDQ0OTU3NzI3In0=
                  parameters:
                    limit: '100'
                  time: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/funds/asset-class-breakdown/{isin}:
    get:
      operationId: funds.asset_class_breakdown
      summary: Fund Asset Class Breakdown
      description: Returns asset-class allocation percentages based on holdings, including recursive look-through of underlying funds and ETFs. Preserves signed weights and reports missing or unclassified exposure as unknown.
      tags:
        - Funds
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/fundIsinPath'
      responses:
        '200':
          description: Holdings-based allocation including explicit unknown weight.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                      - assetClassBreakdown
                    properties:
                      assetClassBreakdown:
                        type: array
                        items:
                          type: object
                          required:
                            - assetClass
                            - percent
                          properties:
                            assetClass:
                              type: string
                              enum:
                                - equity
                                - fixed_income
                                - cash_money_market
                                - commodities
                                - crypto
                                - other
                                - unknown
                            percent:
                              type: number
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  assetClassBreakdown:
                    - assetClass: equity
                      percent: 80
                    - assetClass: fixed_income
                      percent: 20
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/ipo/hot:
    get:
      operationId: ipo.hot
      summary: Hot IPOs
      description: 'Returns the curated list of hot IPO offerings, each with an offering

        summary and a headline financials snapshot (latest full-year period).

        Ordered by implied valuation descending, then public filing date

        descending. Filter by `symbol`, `status`, or a `from`/`to` public-filing

        date range. Supports offset and cursor pagination.'
      tags:
        - IPO
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/HotIPORecord'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - symbol: SPCX
                    name: Space Exploration Technologies Corp.
                    exchange: null
                    regulator: SEC
                    filingType: S-1
                    status: Expected
                    priceType: fixed
                    priceLow: 135.0
                    priceHigh: 135.0
                    currency: USD
                    numberOfShares: 556600000
                    grossProceeds: 75141000000.0
                    impliedValuation: 1750000000000.0
                    confidentialFilingDate: '2026-04-01'
                    publicFilingDate: '2026-05-20'
                    expectedListingDate: '2026-06-12'
                    financialsSnapshot:
                      period: FY2025
                      revenue: 18674.0
                      ebitdaAdjusted: 6584.0
                      netIncome: -4940.0
                      revenueYoY: 0.3324
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 1
                  totalCount: 38
                  parameters:
                    limit: '100'
                  time: 2437
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/ipoSymbolFilterQuery'
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: 'Filter by offering status (e.g. `Expected`, `Priced`, `Listed`). Example when explicitly filtering: `Expected`.'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/ipo/documents:
    get:
      operationId: ipo.documents
      summary: IPO Documents
      description: 'Returns the document catalog for a single IPO (prospectus, SEC filings,

        multi-language prospectus summaries). The optional `language` parameter

        filters documents to the requested language (only that language is

        returned); the optional `type` parameter filters to a single document

        type. Supports offset and cursor pagination.'
      tags:
        - IPO
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IPODocument'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - docType: prospectus
                    label: Prospectus
                    language: en
                    format: pdf
                    isPrimary: true
                    url: null
                  - docType: prospectus_summary
                    label: Prospectus Summary
                    language: en
                    format: pdf
                    isPrimary: true
                    url: null
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 1
                  totalCount: 8
                  parameters:
                    limit: '100'
                    symbol: SPCX
                  time: 2349
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/ipoSymbolQuery'
        - name: language
          in: query
          required: false
          schema:
            type: string
          description: 'Filter documents to this language (ISO 639-1 / BCP-47). Only documents in the requested language are returned; omit for the full multi-language catalog. Example when explicitly filtering: `de`.'
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: 'Filter to a single document type (e.g. `prospectus`, `sec_s1`, `prospectus_summary`). Example when explicitly filtering: `prospectus_summary`.'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/ipo/profile:
    get:
      operationId: ipo.profile
      summary: IPO Profile
      description: 'Returns the full profile for a single IPO: the offering summary plus

        nested milestones, statement-grouped financials (income statement,

        balance sheet, cash flow), and the document catalog. Identify the IPO by

        `symbol` or `isin`. Financials are sourced from the curated hot-IPO

        financials and grouped per statement; each metric carries its fiscal

        year/period, unit, currency, and a `valid` flag. Documents are served

        separately by the /ipo/documents endpoint.'
      tags:
        - IPO
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/IPOProfile'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  symbol: SPCX
                  name: Space Exploration Technologies Corp.
                  exchange: null
                  regulator: SEC
                  filingType: S-1
                  status: Expected
                  priceType: fixed
                  priceLow: 135.0
                  priceHigh: 135.0
                  currency: USD
                  numberOfShares: 556600000
                  grossProceeds: 75141000000.0
                  impliedValuation: 1750000000000.0
                  confidentialFilingDate: '2026-04-01'
                  publicFilingDate: '2026-05-20'
                  milestones:
                    - stage: subscription
                      label: Collecting subscriptions
                      startsAt: null
                      endsAt: '2026-06-10T17:00:00+00:00'
                      expectedDate: null
                      source: EU prospectus
                    - stage: pricing
                      label: Setting price and allocation
                      startsAt: null
                      endsAt: null
                      expectedDate: '2026-06-11'
                      source: S-1
                  financials:
                    incomeStatement:
                      - metric_name: accountsPayable
                        value: 10002000000.0
                        value_type: currency
                        currency: USD
                        unit: USD
                        fiscal_year: 2026
                        fiscal_period: Q1
                        period_end_date: '2026-03-31'
                        source: SpaceX prospectus (S-1) 2026-06-05, consolidated balance sheet
                        valid: true
                      - metric_name: accountsPayable
                        value: 11792000000.0
                        value_type: currency
                        currency: USD
                        unit: USD
                        fiscal_year: 2025
                        fiscal_period: FY
                        period_end_date: '2025-12-31'
                        source: SpaceX prospectus (S-1) 2026-06-05, consolidated balance sheet
                        valid: true
                    balanceSheet:
                      - metric_name: cashAndCashEquivalents
                        value: 15852000000.0
                        value_type: currency
                        currency: USD
                        unit: USD
                        fiscal_year: 2026
                        fiscal_period: Q1
                        period_end_date: '2026-03-31'
                        source: SpaceX EU retail prospectus summary, Bafin-approved 2026-06-05, section B.2
                        valid: true
                      - metric_name: cashAndCashEquivalents
                        value: 24747000000.0
                        value_type: currency
                        currency: USD
                        unit: USD
                        fiscal_year: 2025
                        fiscal_period: FY
                        period_end_date: '2025-12-31'
                        source: SpaceX EU retail prospectus summary, Bafin-approved 2026-06-05, section B.2
                        valid: true
                    cashFlow:
                      - metric_name: capex
                        value: 10107000000.0
                        value_type: currency
                        currency: USD
                        unit: USD
                        fiscal_year: 2026
                        fiscal_period: Q1
                        period_end_date: '2026-03-31'
                        source: SpaceX EU retail prospectus summary, Bafin-approved 2026-06-05, section B.2
                        valid: true
                      - metric_name: capex
                        value: 20737000000.0
                        value_type: currency
                        currency: USD
                        unit: USD
                        fiscal_year: 2025
                        fiscal_period: FY
                        period_end_date: '2025-12-31'
                        source: SpaceX EU retail prospectus summary, Bafin-approved 2026-06-05, section B.2
                        valid: true
                meta:
                  parameters:
                    symbol: SPCX
                  time: 2314
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/ipoSymbolQuery'
  /v2/metrics/{metric_code}/history:
    get:
      operationId: metrics.history
      summary: Metric History
      description: Returns the full time-series history for a specific macroeconomic metric and country. Supports cursor-based pagination for large result sets.
      tags:
        - Economic Indicators
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsHistoryResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  category: inflation
                  country: US
                  from: '1947-01-01'
                  to: '2026-08-01'
                  next_cursor: null
                  metrics:
                    - code: CPI
                      name: CPI All Urban Consumers
                      frequency: Monthly
                      unit: INDEX_1982
                      count: 956
                      data:
                        - reference_period: '2026-07-01'
                          period_end: null
                          value: 333.918
                          is_revised: false
                        - reference_period: '2026-08-01'
                          period_end: null
                          value: 334.98
                          is_revised: false
                    - code: CPI
                      name: CPI All Urban Consumers
                      frequency: Monthly
                      unit: INDEX_2015
                      count: 841
                      data:
                        - reference_period: '2026-01-01'
                          period_end: null
                          value: 2.3864
                          is_revised: false
                        - reference_period: '2026-02-01'
                          period_end: null
                          value: 2.4141
                          is_revised: false
                meta:
                  parameters:
                    metric_code: CPI
                    country: US
                    limit: '1000'
                  time: 2022
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - name: metric_code
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/EconomyMetricCode'
          description: 'Metric code to retrieve history for. See EconomyMetricCode schema for all 63 available codes (e.g. CPI, GDP_REAL, UNEMPLOYMENT_RATE).'
          example: CPI
        - name: country
          in: query
          required: true
          schema:
            type: string
            example: US
          description: ISO 3166-1 alpha-2 country code (e.g. US, DE, JP)
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for the time series (YYYY-MM-DD)
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for the time series (YYYY-MM-DD)
        - name: source
          in: query
          required: false
          schema:
            type: string
          description: 'Filter by data source code (e.g. BLS, FRED, EUROSTAT) Example when explicitly filtering: `BLS`.'
        - name: vintage
          in: query
          required: false
          schema:
            type: string
          description: 'Vintage date for revision tracking. Returns the data as it was known on this date. Example when explicitly filtering: `2026-01-15`.'
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Pagination cursor (reference_period value from previous response's next_cursor). Use instead of from for subsequent pages.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 1000
            minimum: 1
            maximum: 1000
          description: Maximum number of observations to return per page (default 1000, max 1000)
  /v2/news/market:
    get:
      operationId: news.market
      summary: Market News
      description: Returns market-wide financial news. Optionally filter by date range using `from` and `to` parameters.
      tags:
        - News
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsArticle'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - publishedDate: '2026-10-01T19:51:00'
                    title: 'DOOR (OTC: LTCH) Resolves Final Legacy Matter, Completing Four-Year Turnaround of Its Financial Reporting and Legal Obligations'
                    site: prnewswire.com
                    text: 'SEC settlement follows the filing of seven years of financial statements and resolution of four shareholder lawsuits; Company refocuses fully on profitability. ST. LOUIS, Oct. 1, 2026 /PRNewswire/ -- DOOR (OTC: LTCH), today announced that the Securities and Exchange Commission (the "SEC") has approved the Company''s previously disclosed settlement, resolving the SEC''s investigation.'
                    url: https://www.prnewswire.com/news-releases/door-otc-ltch-resolves-final-legacy-matter-completing-four-year-turnaround-of-its-financial-reporting-and-legal-obligations-302896725.html
                  - publishedDate: '2026-10-01T19:43:15'
                    title: 'Nike Q1: The Company Of The Past Is Gone'
                    site: seekingalpha.com
                    text: Nike, Inc. remains unattractive despite a 76% five-year decline, still trading at 21x forward earnings. Q1 earnings revealed a 4% revenue decline, with significant weakness in Europe and Greater China; guidance was notably below consensus. Expense management improved margins, but increased 'demand creation' spending failed to stem revenue losses, highlighting execution and competitive challenges.
                    url: https://seekingalpha.com/article/4951482-nike-q1-the-company-of-the-past-is-gone
                meta:
                  page: 1
                  pageSize: 20
                  totalPages: 2794
                  totalCount: 55862
                  parameters:
                    limit: '20'
                  time: 34
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/newsLimitQuery'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/news/stock:
    get:
      operationId: news.byStock
      summary: Stock News
      description: Returns recent news articles for a specific stock. Optionally filter by date range using `from` and `to` parameters.


        One of the query parameters `symbol`, `isin` is required; each is optional on its own (`x-one-of-parameters`).
      tags:
        - News
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsArticle'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - symbol: null
                    publishedDate: '2026-09-27T15:45:00'
                    title: Apple and Nvidia Are the Two Largest Companies in the World. Which is the Better Stock to Buy?
                    site: fool.com
                    text: Nvidia's growth rate will blow Apple away over the next year. Apple's stock is very pricey compared to Nvidia's.
                    url: https://www.fool.com/investing/2026/09/27/apple-nvidia-largest-companies-better-stock/
                  - symbol: null
                    publishedDate: '2026-09-26T21:46:05'
                    title: US jury says Apple owes record $5.7 billion in patent case against San Diego company
                    site: nypost.com
                    text: A US jury ruled that Apple owes Taction over $5.7 billion for infringing haptic technology patents in iPhones and Apple Watches.
                    url: https://nypost.com/2026/09/26/business/us-jury-says-apple-owes-record-5-7-billion-in-patent-case-against-san-diego-company/
                meta:
                  parameters:
                    limit: '20'
                    symbol: AAPL
                  time: 16
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/symbolQuery'
        - $ref: '#/components/parameters/isinQuery'
        - $ref: '#/components/parameters/newsLimitQuery'
        - $ref: '#/components/parameters/fromQuery'
        - $ref: '#/components/parameters/toQuery'
        - $ref: '#/components/parameters/cursorQuery'
      x-one-of-parameters:
        - - symbol
          - isin
  /v2/quant-os/allocate:
    post:
      operationId: bavest.quantos.allocate
      summary: QuantOS Allocation Exposure
      description: Compute optimal allocation weights for a portfolio.
      tags:
        - Bavest QuantOS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        symbol:
                          type: string
                        percentage:
                          type: number
                          format: double
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - symbol: AAPL
                    percentage: 40.0
                  - symbol: MSFT
                    percentage: 35.0
                meta:
                  parameters:
                    startDate: '2026-09-01'
                    endDate: '2026-09-30'
                    currency: USD
                    resolution: D
                    portfolio_items:
                      - symbol: AAPL
                        weight: 0.4
                        buy_date: 1788220800000
                      - symbol: MSFT
                        weight: 0.35
                        buy_date: 1788220800000
                      - symbol: GOOGL
                        weight: 0.25
                        buy_date: 1788220800000
                    from: 1788220800
                    to: 1790726400
                  time: 5130
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        $ref: '#/components/requestBodies/QuantOSPortfolio'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/quant-os/chart:
    post:
      operationId: bavest.quantos.chart
      summary: QuantOS Performance Chart
      description: Generate performance chart data for a portfolio over a date range.
      tags:
        - Bavest QuantOS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/QuantOSChart'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  t:
                    - 1788220800.0
                    - 1788264000.0
                  c:
                    - 389.164
                    - 388.6575
                meta:
                  parameters:
                    startDate: '2026-09-01'
                    endDate: '2026-09-30'
                    currency: USD
                    resolution: D
                    portfolio_items:
                      - symbol: AAPL
                        weight: 0.4
                        buy_date: 1788220800000
                      - symbol: MSFT
                        weight: 0.35
                        buy_date: 1788220800000
                      - symbol: GOOGL
                        weight: 0.25
                        buy_date: 1788220800000
                    from: 1788220800
                    to: 1790726400
                    enable_portfolio_chart: true
                  time: 6794
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        $ref: '#/components/requestBodies/QuantOSPortfolio'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/quant-os/price:
    post:
      operationId: bavest.quantos.price
      summary: QuantOS Valuation
      description: Calculate current portfolio position value.
      tags:
        - Bavest QuantOS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/QuantOSPrice'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  currentPrice: 396.168
                  open: 401.6555
                  low: 393.461
                  high: 404.2945
                  changePercent: -0.2518
                  change: -2.575
                  previousClose: 398.743
                  timestamp: 1790950835
                  failed: []
                meta:
                  parameters:
                    startDate: '2026-09-01'
                    endDate: '2026-09-30'
                    currency: USD
                    resolution: D
                    portfolio_items:
                      - symbol: AAPL
                        weight: 0.4
                        buy_date: 1788220800000
                      - symbol: MSFT
                        weight: 0.35
                        buy_date: 1788220800000
                      - symbol: GOOGL
                        weight: 0.25
                        buy_date: 1788220800000
                    from: 1788220800
                    to: 1790726400
                  time: 5936
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        $ref: '#/components/requestBodies/QuantOSPortfolio'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/quant-os/region:
    post:
      operationId: bavest.quantos.regions
      summary: QuantOS Region Breakdown
      description: Break down portfolio holdings by geographic region.
      tags:
        - Bavest QuantOS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        region:
                          type: string
                          description: Geographic region name
                        percentage:
                          type: number
                          format: double
                          description: Allocation percentage
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - region: US
                    percentage: 100.0
                meta:
                  parameters:
                    startDate: '2026-09-01'
                    endDate: '2026-09-30'
                    currency: USD
                    resolution: D
                    portfolio_items:
                      - symbol: AAPL
                        weight: 0.4
                        buy_date: 1788220800000
                      - symbol: MSFT
                        weight: 0.35
                        buy_date: 1788220800000
                      - symbol: GOOGL
                        weight: 0.25
                        buy_date: 1788220800000
                    from: 1788220800
                    to: 1790726400
                  time: 6138
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        $ref: '#/components/requestBodies/QuantOSPortfolio'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/quant-os/return:
    post:
      operationId: bavest.quantos.returns
      summary: QuantOS Portfolio Return
      description: Calculate portfolio return over a specified period.
      tags:
        - Bavest QuantOS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/QuantOSReturn'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  beta: 0.0
                  performanceSixMonths: 15.7361
                  performanceOneWeek: 0.2813
                  performanceOneYear: 13.9087
                  dividendPerShareAnnual: 0.0
                meta:
                  parameters:
                    startDate: '2026-09-01'
                    endDate: '2026-09-30'
                    currency: USD
                    resolution: D
                    portfolio_items:
                      - symbol: AAPL
                        weight: 0.4
                        buy_date: 1788220800000
                      - symbol: MSFT
                        weight: 0.35
                        buy_date: 1788220800000
                      - symbol: GOOGL
                        weight: 0.25
                        buy_date: 1788220800000
                    from: 1788220800
                    to: 1790726400
                  time: 7337
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        $ref: '#/components/requestBodies/QuantOSPortfolio'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/quant-os/sector:
    post:
      operationId: bavest.quantos.sectors
      summary: QuantOS Sector Breakdown
      description: Break down portfolio holdings by GICS sector.
      tags:
        - Bavest QuantOS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        sector:
                          type: string
                          description: GICS sector name
                        percentage:
                          type: number
                          format: double
                          description: Allocation percentage
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  - sector: Technology
                    percentage: 75.0
                  - sector: Communication Services
                    percentage: 25.0
                meta:
                  parameters:
                    startDate: '2026-09-01'
                    endDate: '2026-09-30'
                    currency: USD
                    resolution: D
                    portfolio_items:
                      - symbol: AAPL
                        weight: 0.4
                        buy_date: 1788220800000
                      - symbol: MSFT
                        weight: 0.35
                        buy_date: 1788220800000
                      - symbol: GOOGL
                        weight: 0.25
                        buy_date: 1788220800000
                    from: 1788220800
                    to: 1790726400
                  time: 5962
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        $ref: '#/components/requestBodies/QuantOSPortfolio'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/quant-os/stats:
    post:
      operationId: bavest.quantos.stats
      summary: QuantOS Statistics
      description: Returns comprehensive portfolio statistics including returns, risk, and ratios.
      tags:
        - Bavest QuantOS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/QuantOSStats'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                data:
                  '0':
                    sharpeRatio: '0.86'
                    correlation:
                      '0': 1
                      '1': '0.23'
                      total: '0.61'
                    series:
                      t:
                        - 1735819200
                      c:
                        - -0.001
                      h: []
                      l: []
                      o: []
                      s: ok
                      v: []
                    stats:
                      riskFree: 0.7
                      totalReturn: 3.1483
                      cagr: 2.1732
                      maxDrawdown: -0.2838
                      calmar: 7.6564
                      mtd: -0.0437
                      threeMonth: -0.0752
                      sixMonth: -0.0094
                      ytd: -0.0691
                      oneYear: 0.1356
                      threeYear: 2.1732
                      fiveYear: null
                      tenYear: null
                      inception: 2.1732
                      dailySharpe: 0.5308
                      dailySortino: 6.8143
                      dailyMean: 1.341
                      dailyVolume: 1.5257
                      dailySkew: 20.0825
                      dailyKurt: 416.0306
                      bestDay: 2.0
                      worstDay: -0.0831
                      monthlySharpe: 0.7119
                      monthlySortino: 12.0393
                      monthlyMean: 2.3582
                      monthlyVol: 2.5504
                      monthlySkew: 3.8309
                      monthlyKurt: 14.7666
                      bestMonth: 2.8494
                      worstMonth: -0.0769
                      yearlySharpe: 0.3986
                      yearlySortino: 1.8269
                      yearlyMean: 1.6935
                      yearlyVol: 2.4926
                      yearlySkew: null
                      yearlyKurt: null
                      bestYear: 3.456
                      worstYear: -0.0691
                      avgDrawdown: -0.0681
                      avgDrawdownDays: 45.4444
                      avgUpMonth: 0.4627
                      avgDownMonth: -0.0364
                      winYearPerc: 0.5
                      twelveMonthWinPerc: 1.0
                    error: null
                  '1':
                    sharpeRatio: '0.76'
                    correlation:
                      '0': '0.23'
                      '1': 1
                      total: '0.91'
                    series:
                      t:
                        - 1736164800
                      c:
                        - -0.0064
                      h: []
                      l: []
                      o: []
                      s: ok
                      v: []
                    stats:
                      riskFree: 0.7
                      totalReturn: 2.4973
                      cagr: 1.7626
                      maxDrawdown: -0.3245
                      calmar: 5.4312
                      mtd: -0.075
                      threeMonth: -0.2495
                      sixMonth: -0.2852
                      ytd: -0.2391
                      oneYear: -0.0623
                      threeYear: 1.7626
                      fiveYear: null
                      tenYear: null
                      inception: 1.7626
                      dailySharpe: 0.4671
                      dailySortino: 6.7901
                      dailyMean: 1.2436
                      dailyVolume: 1.5252
                      dailySkew: 20.1235
                      dailyKurt: 416.9528
                      bestDay: 2.0
                      worstDay: -0.0561
                      monthlySharpe: 0.6578
                      monthlySortino: 9.3706
                      monthlyMean: 2.2948
                      monthlyVol: 2.6637
                      monthlySkew: 3.8205
                      monthlyKurt: 14.7093
                      bestMonth: 2.9598
                      worstMonth: -0.1125
                      yearlySharpe: 0.3608
                      yearlySortino: 1.4736
                      yearlyMean: 1.6785
                      yearlyVol: 2.7118
                      yearlySkew: null
                      yearlyKurt: null
                      bestYear: 3.596
                      worstYear: -0.2391
                      avgDrawdown: -0.0378
                      avgDrawdownDays: 21.5
                      avgUpMonth: 0.5558
                      avgDownMonth: -0.0518
                      winYearPerc: 0.5
                      twelveMonthWinPerc: 0.8
                    error: null
                  total:
                    sharpeRatio: '0.80'
                    correlation:
                      '0': '0.61'
                      '1': '0.91'
                      total: 1
                    series:
                      t:
                        - 1736164800
                      c:
                        - -0.0061
                      h: []
                      l: []
                      o: []
                      s: ok
                      v: []
                    stats:
                      riskFree: 0.7
                      totalReturn: 2.7369
                      cagr: 1.9153
                      maxDrawdown: -0.2371
                      calmar: 8.0793
                      mtd: -0.0625
                      threeMonth: -0.1869
                      sixMonth: -0.1934
                      ytd: -0.1777
                      oneYear: 0.0096
                      threeYear: 1.9153
                      fiveYear: null
                      tenYear: null
                      inception: 1.9153
                      dailySharpe: 0.4899
                      dailySortino: 8.2368
                      dailyMean: 1.2772
                      dailyVolume: 1.5227
                      dailySkew: 20.2169
                      dailyKurt: 419.6071
                      bestDay: 2.0
                      worstDay: -0.0489
                      monthlySharpe: 0.675
                      monthlySortino: 11.2402
                      monthlyMean: 2.3096
                      monthlyVol: 2.618
                      monthlySkew: 3.8472
                      monthlyKurt: 14.8585
                      bestMonth: 2.9191
                      worstMonth: -0.0811
                      yearlySharpe: 0.3736
                      yearlySortino: 1.5845
                      yearlyMean: 1.6834
                      yearlyVol: 2.632
                      yearlySkew: null
                      yearlyKurt: null
                      bestYear: 3.5445
                      worstYear: -0.1777
                      avgDrawdown: -0.0428
                      avgDrawdownDays: 28.4286
                      avgUpMonth: 0.3995
                      avgDownMonth: -0.0441
                      winYearPerc: 0.5
                      twelveMonthWinPerc: 0.8
                    error: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        $ref: '#/components/requestBodies/QuantOSPortfolio'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/adrs/list:
    get:
      operationId: reference.adrList
      summary: ADR List
      description: Returns a paginated list of all American Depositary Receipts (ADRs).
      tags:
        - Reference
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecurityListItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - isin: US88025U1097
                    symbol: TXG
                    name: 10x Genomics, Inc.
                    country: US
                    exchange: NASDAQ Global Select
                    exchangeCode: NASDAQ
                    sector: Healthcare
                  - isin: US88025U1097
                    symbol: 1KJ.TG
                    name: 10x Genomics, Inc.
                    country: null
                    exchange: null
                    exchangeCode: null
                    sector: null
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 161
                  totalCount: 16088
                  nextCursor: eyJuYW1lIjogIkFCIExhcmdlIENhcCBHcm93dGggRnVuZCBBZHZpc29yIENsYXNzIiwgImlzaW4iOiAiVVMwMTg3N0M0MDg3IiwgIl9pZCI6ICIwYzdiZjZjMS1mNzk3LTQ0MWItOTdkNS0zYTc4ZjE5ZTliMGIifQ==
                  parameters:
                    limit: '100'
                  time: 5
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
        - name: exchangeCode
          in: query
          required: false
          schema:
            type: string
          description: 'Filter by exchange short code (e.g. NASDAQ, NYSE) Example when explicitly filtering: `NASDAQ`.'
  /v2/securities/list:
    get:
      operationId: reference.securityList
      summary: Security List
      description: Returns a paginated list of all stock securities.
      tags:
        - Reference
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecurityListItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - isin: CA98955B1040
                    symbol: LNXGF
                    name: 0187279 B.C. Ltd.
                    country: CA
                    exchange: Other OTC
                    exchangeCode: OTC
                    sector: Financial Services
                  - isin: CA98956J1066
                    symbol: OONEF
                    name: 01 Quantum Inc.
                    country: CA
                    exchange: Other OTC
                    exchangeCode: OTC
                    sector: Technology
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 777
                  totalCount: 77641
                  nextCursor: eyJuYW1lIjogIjNEIEdsb2JhbCBCaW90ZWNoIEluYy4iLCAiaXNpbiI6ICJUVzAwMDY4MDgwMDkiLCAiX2lkIjogImQwMTAyNzFiLWU3NGQtNGMxZC1iNmM0LWI0NTEyMTMxYjJkNiJ9
                  parameters:
                    limit: '100'
                  time: 5
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
        - name: exchangeCode
          in: query
          required: false
          schema:
            type: string
          description: 'Filter by exchange short code (e.g. NASDAQ, NYSE) Example when explicitly filtering: `NASDAQ`.'
  /v2/securities/delisted:
    get:
      operationId: reference.delistedList
      summary: Delisted Securities List
      description: Returns a paginated list of delisted securities (lifecycle status 'delisted' — isActivelyTrading became false with no successor). Optionally filter by security type.
      tags:
        - Reference
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DelistedSecurityListItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - isin: null
                    symbol: FBG
                    name: UBS AG FI Enhanced Big Cap Growth ETN
                    type: MUTUAL_FUND
                    exchange: NASDAQ
                    deprecatedAt: '2026-09-22T07:02:08.021738+00:00'
                    deprecationReason: delisted
                  - isin: US4566771030
                    symbol: ZVAMIX
                    name: Infinity Core Alternative Fund
                    type: ADR
                    exchange: NASDAQ
                    deprecatedAt: '2026-06-30T15:12:41.045839+00:00'
                    deprecationReason: delisted
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 211
                  totalCount: 21031
                  parameters:
                    limit: '100'
                  time: 3343
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: 'Filter by security type (e.g. EQUITY, ETF, ADR) Example when explicitly filtering: `EQUITY`.'
  /v2/securities/isin-changed:
    get:
      operationId: reference.isinChangeList
      summary: ISIN Change List
      description: Returns a paginated list of securities whose ISIN changed, with the old and new ISIN. The old row was deprecated (deprecation_reason 'isin_changed') and superseded by a new active row for the same instrument. Optionally filter by security type.
      tags:
        - Reference
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IsinChangeListItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - oldIsin: CA08662X4066
                    newIsin: CA08662X6046
                    symbol: SLVD.TO
                    name: BetaPro Silver -2x Daily Bear ETF
                    type: ETF
                    exchange: TSX
                    changedAt: '2026-10-02T07:04:22.931218+00:00'
                    deprecationReason: symbol_changed
                  - oldIsin: TH0922B10Z07
                    newIsin: TH0922D10Z05
                    symbol: PSGC.BK
                    name: PSG Corporation Public Company Limited
                    type: EQUITY
                    exchange: SET
                    changedAt: '2026-10-02T07:04:22.931218+00:00'
                    deprecationReason: symbol_changed
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 32
                  totalCount: 3127
                  parameters:
                    limit: '100'
                  time: 6035
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: 'Filter by security type (e.g. EQUITY, ETF, ADR) Example when explicitly filtering: `EQUITY`.'
  /v2/reference/search:
    get:
      operationId: reference.search
      summary: Security Search
      description: Search across stocks, ETFs, funds, and crypto by name or ticker.
      tags:
        - Reference
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - symbol: APC.DE
                    companyName: Apple Inc.
                    isin: US0378331005
                    type: ADR
                    subtype: null
                    isEtf: false
                    isAdr: true
                    isFund: false
                    exchange: XETRA
                    isActivelyTrading: true
                  - symbol: AAPL
                    companyName: Apple Inc.
                    isin: US0378331005
                    type: EQUITY
                    subtype: null
                    isEtf: false
                    isAdr: false
                    isFund: false
                    exchange: NASDAQ
                    isActivelyTrading: true
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 2
                  totalCount: 104
                  parameters:
                    limit: '100'
                    q: Apple
                  time: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - name: q
          in: query
          required: true
          schema:
            type: string
            example: Apple
          description: Search query (name, ticker, or ISIN)
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/reference/search/aggregated:
    get:
      operationId: reference.searchAggregated
      summary: Security Search Aggregated
      description: Returns aggregated search results grouped by security type.
      tags:
        - Reference
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Security name
                            listings:
                              type: array
                              items:
                                $ref: '#/components/schemas/SearchResult'
                            root_ticker:
                              type: string
                              description: Primary ticker symbol
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  results:
                    - name: Tesla, Inc.
                      listings:
                        - symbol: TL0.DE
                          isin: US88160R1014
                          exchange: XETRA
                          type: ADR
                          isEtf: false
                          isAdr: true
                          isFund: false
                        - symbol: TSLA
                          isin: US88160R1014
                          exchange: NASDAQ
                          type: EQUITY
                          isEtf: false
                          isAdr: false
                          isFund: false
                      root_ticker: TSLA
                    - name: Tesla Exploration Ltd.
                      listings:
                        - symbol: TXLZF
                          isin: CA8816011081
                          exchange: PNK
                          type: EQUITY
                          isEtf: false
                          isAdr: false
                          isFund: false
                      root_ticker: TXLZF
                meta:
                  page: 1
                  pageSize: 100
                  totalPages: 1
                  totalCount: 45
                  parameters:
                    limit: '100'
                    q: Tesla
                  time: 198
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
        - name: q
          in: query
          required: true
          schema:
            type: string
            example: Tesla
          description: Search query (name, ticker, or ISIN)
        - $ref: '#/components/parameters/limitQuery'
        - $ref: '#/components/parameters/offsetQuery'
        - $ref: '#/components/parameters/cursorQuery'
  /v2/reference/screener:
    post:
      operationId: reference.screen
      summary: Stock Screener
      description: 'Filter securities by financial metrics, profile attributes, valuation multiples, stability ratios, ESG scores, and more. All query conditions are combined with AND. Results include the requested metric values alongside each security''s symbol, name, and ISIN.'
      tags:
        - Reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: array
                  description: 'List of filter conditions. All conditions are combined with AND logic. Each item specifies a metric, comparison operator, and threshold value.'
                  items:
                    $ref: '#/components/schemas/ScreenerFilterItem'
                sort:
                  type: array
                  description: 'Optional list of sort criteria applied in order. When omitted, the default result ordering is used.'
                  items:
                    $ref: '#/components/schemas/ScreenerSortItem'
                offset:
                  type: integer
                  description: Pagination offset (number of results to skip).
                  default: 0
                  example: 0
                limit:
                  type: integer
                  description: Maximum number of results to return.
                  default: 100
                  example: 10
                currency:
                  type: string
                  description: 'Target currency for value conversion. When set, monetary metric values are converted to this currency.'
                  example: EUR
            example:
              query:
                - metric: returnOnEquity
                  operator: gte
                  value: 10
                - metric: sector
                  operator: eq
                  value: Technology
                - metric: marketCapitalization
                  operator: gte
                  value: 1000000000
              sort:
                - metric: marketCapitalization
                  order: desc
              offset: 0
              limit: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScreenerResult'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - symbol: ASAN
                    name: Asana, Inc.
                    isin: US04342Y1047
                    marketCapitalization: 2083961217.0
                    returnOnEquity: 16.5541
                    sector: Technology
                meta:
                  page: 1
                  pageSize: 10
                  totalPages: 1
                  totalCount: 1
                  parameters:
                    query:
                      - metric: returnOnEquity
                        operator: gte
                        value: 10
                      - metric: sector
                        operator: eq
                        value: Technology
                    sort:
                      - metric: marketCapitalization
                        order: desc
                    offset: 0
                    limit: 10
                  time: 447
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/acceptJson'
  /v2/mcp:
    post:
      operationId: ai.mcp
      summary: MCP Server
      description: "Model Context Protocol (MCP) server for AI agents. Connect any MCP client (Claude, ChatGPT, Cursor, VS Code, Windsurf or your own agent) to one URL, `https://api.bavest.co/v2/mcp`, and use the Bavest v2 data routes as tools.


        ## Quick start


        ```json

        {

        \  \"mcpServers\": {

        \    \"bavest\": {

        \      \"url\": \"https://api.bavest.co/v2/mcp\",

        \      \"headers\": { \"x-api-key\": \"YOUR_API_KEY\" }

        \    }

        \  }

        }

        ```


        ## Tools


        Each tool wraps one REST route and is named after the route's `operationId` in snake case: `equities.profile` is `equities_profile`, `etfs.topHoldings` is `etfs_top_holdings`. `initialize` and `tools/list` work without a key and return the exact names and input schemas. A tool call counts against your plan like the REST call it wraps; a route outside your plan answers with an error.


        ## Authentication


        Send your API key in the `x-api-key` header, as on every REST route. Connectors that can only take a URL (Claude custom connectors, ChatGPT developer mode) may pass the same key as the optional `api_key` query parameter instead. URLs end up in logs and settings exports, so prefer the header."
      tags:
        - AI
      requestBody:
        required: true
        description: JSON-RPC 2.0 request following the MCP specification.
        content:
          application/json:
            schema:
              type: object
              required:
                - jsonrpc
                - method
              properties:
                jsonrpc:
                  type: string
                  description: JSON-RPC protocol version
                  enum:
                    - '2.0'
                id:
                  type: string
                  description: Request identifier (omit for notifications)
                method:
                  type: string
                  description: MCP method to invoke
                  enum:
                    - initialize
                    - tools/list
                    - tools/call
                    - ping
                params:
                  type: object
                  description: Method parameters (varies by method)
            examples:
              initialize:
                summary: Initialize handshake
                value:
                  jsonrpc: '2.0'
                  id: '1'
                  method: initialize
                  params:
                    protocolVersion: '2025-03-26'
                    capabilities: {}
                    clientInfo:
                      name: my-agent
                      version: '1.0'
              tools_list:
                summary: List available tools
                value:
                  jsonrpc: '2.0'
                  id: '2'
                  method: tools/list
                  params: {}
              tools_call:
                summary: Call a tool
                value:
                  jsonrpc: '2.0'
                  id: '3'
                  method: tools/call
                  params:
                    name: equities_profile
                    arguments:
                      symbol: AAPL
      responses:
        '200':
          description: MCP server response. The response format follows the Model Context Protocol specification and varies based on the MCP method invoked by the client.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                    description: JSON-RPC version
                    example: '2.0'
                  id:
                    type: string
                    description: Request identifier
                  result:
                    type: object
                    description: MCP response payload (varies by method)
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              example:
                jsonrpc: "2.0"
                id: "1"
                result:
                  protocolVersion: 2025-03-26
                  capabilities:
                    tools:
                      listChanged: false
                  serverInfo:
                    name: bavest-financial-data
                    version: 1.0.0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: api_key
          in: query
          required: false
          schema:
            type: string
          description: "Optional. Your API key in the URL, for MCP connectors that cannot set headers. Prefer the `x-api-key` header: URLs end up in logs."
        - $ref: '#/components/parameters/acceptJson'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Get one at [dashboard.bavest.co/sign-up](https://dashboard.bavest.co/sign-up).
      x-default: demo_api_key
  parameters:
    symbolQuery:
      name: symbol
      in: query
      required: false
      schema:
        type: string
        example: AAPL
      description: Stock ticker symbol (e.g., `AAPL`, `MSFT`, `GOOGL`). Provide exactly one of symbol or isin.
    ipoSymbolQuery:
      name: symbol
      in: query
      required: false
      schema:
        type: string
        example: SPCX
      description: IPO ticker symbol (e.g., `SPCX` for SpaceX). Symbol only — ISIN is not supported for IPO endpoints.
    isinQuery:
      name: isin
      in: query
      required: false
      schema:
        type: string
        pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
        minLength: 12
        maxLength: 12
      description: ISIN code (e.g., `US0378331005`). Provide exactly one of symbol or isin. Clear the symbol example before using an ISIN.
    cusipQuery:
      name: cusip
      in: query
      required: false
      schema:
        type: string
        minLength: 9
        maxLength: 9
      description: CUSIP code (e.g., `037833100`). Provide at most one of symbol, isin, or cusip.
    cryptoSymbolQuery:
      name: symbol
      in: query
      required: true
      schema:
        type: string
        example: BTCUSD
      description: Cryptocurrency pair symbol (e.g., `BTCUSD`, `ETHUSD`, `SOLUSD`).
    etfSymbolQuery:
      name: symbol
      in: query
      required: false
      schema:
        type: string
      description: ETF ticker symbol (e.g., `IWDA.AS`). Provide exactly one of symbol or isin; clear the ISIN example before using a symbol.
    etfIsinQuery:
      name: isin
      in: query
      required: false
      schema:
        type: string
        example: IE00B4L5Y983
        pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
        minLength: 12
        maxLength: 12
      description: ETF ISIN code (e.g., `IE00B4L5Y983`, iShares Core MSCI World UCITS ETF). Provide exactly one of symbol or isin.
    etfViewQuery:
      name: view
      in: query
      required: false
      schema:
        type: string
        enum:
          - display
          - raw
        default: display
      description: Allocation view. `display` (default) hides rows with negative exposure and scales the remainder to 100. `raw` returns the stored rates, where swap/bond legs and short positions are legitimately negative. Unrecognized values fall back to `display`.
    holdingsViewQuery:
      name: view
      in: query
      required: false
      schema:
        type: string
        enum:
          - display
          - raw
        default: display
      description: Holdings view. `display` (default) weighs every row by market value, so a fund sums to ~100, with cash, Treasury bills and money market funds as their own rows; swaps and futures (no market value) and negative cash rows are left out. `raw` lists every row and keeps the issuer's exposure weights, so derivatives count at notional (a 3x fund ~300) and swaps list their counterparty. Plain ETFs are the same in both views. Unrecognized values fall back to `display`.
    fundIsinPath:
      name: isin
      in: path
      required: true
      schema:
        type: string
        example: DE0009848119
        pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
        minLength: 12
        maxLength: 12
      description: Fund ISIN code (e.g., `DE0009848119`)
    pairPath:
      name: pair
      in: path
      required: true
      schema:
        type: string
        example: EURUSD
      description: Currency pair (e.g., `EURUSD`, `GBPJPY`)
    countryPath:
      name: country
      in: path
      required: true
      schema:
        type: string
        example: US
        pattern: ^[A-Z]{2}$
        minLength: 2
        maxLength: 2
      description: ISO 3166-1 alpha-2 country code (e.g., `US`, `DE`, `JP`)
    frequencyQuery:
      name: freq
      in: query
      required: false
      schema:
        type: string
        enum:
          - annual
          - quarterly
        default: annual
      description: Reporting frequency
      x-enumDescriptions:
        annual: Full fiscal year (FY) reporting period
        quarterly: Quarterly (Q1-Q4) reporting period
    statementProvenanceQuery:
      name: provenance
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: 'When true, the response carries a `provenance` block with one entry per served statement date: where the numbers come from, when we got them, and whether they changed since. Entries are explicitly null when observation history is unavailable for the security.'
    fromQuery:
      name: from
      in: query
      required: false
      schema:
        type: string
        format: date
      description: Start date (YYYY-MM-DD)
    toQuery:
      name: to
      in: query
      required: false
      schema:
        type: string
        format: date
      description: End date (YYYY-MM-DD)
    limitQuery:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 100
        minimum: 1
        maximum: 1000
      description: Maximum number of results to return (default 100, max 1000)
    offsetQuery:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 0
        minimum: 0
      description: Number of results to skip for pagination (default 0)
    cursorQuery:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      description: Opaque cursor for cursor-based pagination. When provided, returns results after the cursor position. Takes precedence over offset.
    updatedSinceQuery:
      name: updated_since
      in: query
      required: false
      schema:
        type: string
        format: date-time
      description: Delta-polling cursor start. Accepts an ISO-8601 date or date-time. When set, results are sorted `updated_at` ascending instead of `filed_at` descending — the recommended low-latency polling pattern, since it guarantees a cursor never skips a row that was updated between polls.
    filingsLimitQuery:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 50
        minimum: 1
        maximum: 500
      description: Maximum number of results to return (default 50, max 500)
    newsLimitQuery:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
      description: Maximum number of articles to return (default 20, max 100)
    fromQueryRequired:
      name: from
      in: query
      required: true
      schema:
        type: string
        format: date
        example: '2026-09-01'
      description: Start date (YYYY-MM-DD). Required for candle data.
    toQueryRequired:
      name: to
      in: query
      required: true
      schema:
        type: string
        format: date
        example: '2026-09-30'
      description: End date (YYYY-MM-DD). Required for candle data.
    resolutionQuery:
      name: resolution
      in: query
      required: false
      schema:
        type: string
        enum:
          - D
          - W
          - M
        default: D
      description: Candle resolution
      x-enumDescriptions:
        D: Daily bars
        W: Weekly bars
        M: Monthly bars
    intradayResolutionQuery:
      name: resolution
      in: query
      required: false
      schema:
        type: string
        enum:
          - '1'
          - '5'
          - '15'
          - '60'
        default: '1'
      description: Intraday bar resolution in minutes
      x-enumDescriptions:
        '1': 1-minute bars
        '5': 5-minute bars
        '15': 15-minute bars
        '60': 60-minute bars
    fieldsQueryBalanceSheet:
      name: fields
      in: query
      required: false
      schema:
        type: string
      description: 'Comma-separated list of balance sheet line items to include. When provided, each statement is reduced to the named line items. Names that are not balance sheet line items match nothing, so a statement reduced by them comes back empty. Example when explicitly filtering: `totalAssets,totalLiabilities,totalEquity`.'
    fieldsQueryCashFlow:
      name: fields
      in: query
      required: false
      schema:
        type: string
      description: 'Comma-separated list of cash flow line items to include. When provided, each statement is reduced to the named line items. Names that are not cash flow line items match nothing, so a statement reduced by them comes back empty. Example when explicitly filtering: `netOperatingCashFlow,capex,freeCashFlow`.'
    fieldsQueryIncomeStatement:
      name: fields
      in: query
      required: false
      schema:
        type: string
      description: 'Comma-separated list of income statement line items to include. When provided, each statement is reduced to the named line items. Names that are not income statement line items match nothing, so a statement reduced by them comes back empty. Example when explicitly filtering: `revenue,netIncome,eps`.'
    fieldsQueryFinancialsTtm:
      name: fields
      in: query
      required: false
      schema:
        type: string
      description: 'Comma-separated list of line items to include. The filter is applied to each of the `bs`, `cf` and `ic` blocks, so a name is kept only in the statement that reports it. Names that no statement reports match nothing, so the blocks come back empty. Example when explicitly filtering: `totalAssets,freeCashFlow,revenue`.'
    fieldsQueryMetrics:
      name: fields
      in: query
      required: false
      schema:
        type: string
      description: 'Comma-separated list of metric ids to return. Unlike the statement endpoints, this filters metrics by `metricId`, not by response key. Valid ids are served by `/v2/equities/metrics/names`. Ids that do not exist match nothing, so the metrics list comes back empty. Example when explicitly filtering: `market_cap,roe_ttm`.'
    acceptJson:
      name: Accept
      in: header
      required: false
      schema:
        type: string
        default: application/json
      description: Response content type. Defaults to `application/json`.
    symbolFilterQuery:
      name: symbol
      in: query
      required: false
      schema:
        type: string
      description: Optional ticker filter (e.g., `AAPL`). Omit for all securities. Provide at most one of symbol or isin.
    ipoSymbolFilterQuery:
      name: symbol
      in: query
      required: false
      schema:
        type: string
      description: Optional IPO ticker filter (e.g., `SPCX`). Omit for all offerings.
  requestBodies:
    QuantOSPortfolio:
      required: true
      description: Symbols, weights, and date range for analysis.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QuantOSRequest'
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Missing Authentication Token
            status: ERROR
    NotFound:
      description: Resource not found.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: The requested security is not found.
            status: ERROR
    RateLimited:
      description: Rate limit exceeded. Retry after the `Retry-After` header interval.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Rate limit exceeded. Please retry after cooldown.
            status: ERROR
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          schema:
            type: integer
          description: Seconds until rate limit resets
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests in current window
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests allowed in current window
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp when the rate limit window resets
    ServiceUnavailable:
      description: Bavest cannot read its data store right now. The security may well have data; retry after the `Retry-After` header interval.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Bavest data store unavailable. Retry later.
            status: ERROR
    BadRequest:
      description: Invalid request parameters. Returned when required query parameters are missing, have invalid types, or violate constraints (e.g., providing both symbol and isin when they are mutually exclusive).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Either 'symbol', 'isin', or 'cusip' must be provided.
            status: ERROR
    BadGateway:
      description: Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Upstream data provider is temporarily unavailable. Please retry after a short delay.
            status: ERROR
    GatewayTimeout:
      description: The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Request timed out waiting for upstream data provider. Consider narrowing your date range or simplifying the query.
            status: ERROR
    InternalServerError:
      description: An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Bavest server error.
            status: ERROR
  headers:
    CacheControl:
      schema:
        type: string
      description: Cache control directive for response caching
      example: max-age=300
    RequestId:
      schema:
        type: string
        format: uuid
      description: Unique request identifier for tracing and debugging. Present on every response.
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    BulkRequest:
      type: object
      description: Bulk request to fan out a single endpoint across multiple symbols or ISINs.
      oneOf:
        - required:
            - symbols
            - endpoint
        - required:
            - isins
            - endpoint
      properties:
        symbols:
          type: array
          description: List of per-symbol parameter objects. Each object is merged with `params` and sent to the target endpoint. Provide exactly one of `symbols` or `isins`.
          maxItems: 100
          items:
            type: object
            properties:
              symbol:
                type: string
                description: Ticker symbol
                example: AAPL
              currency:
                type: string
                description: Target currency (ISO 4217)
            required:
              - symbol
          example:
            - symbol: AAPL
            - symbol: MSFT
        isins:
          type: array
          description: List of per-ISIN parameter objects. Each object is merged with `params` and sent to the target endpoint. Provide exactly one of `symbols` or `isins`.
          maxItems: 100
          items:
            type: object
            properties:
              isin:
                type: string
                description: ISIN code
            required:
              - isin
        endpoint:
          type: string
          description: Target endpoint key. Selects the endpoint used for each entry. market_cap returns equity, ETF or fund metrics according to the asset type. Returns the target metrics response with its metric names, units, currency, and pagination, selecting market_cap for equities and aum/fund_aum for funds by default. Fund AUM is not equity market capitalization. Use params.fields to override this selection and params.limit/offset to page it. dividends_history is an alias for dividend and etf_dividend and uses the dividend-history endpoint.
          enum:
            - search
            - etf_country
            - etf_profile
            - etf_top_holdings
            - etf_top_sectors
            - etf_holdings
            - etf_sector
            - etf_metrics
            - fund_metrics
            - etf_dividend
            - crypto_price
            - dividend
            - stock_profile
            - stock_metric
            - balance_sheet
            - cash_flow
            - income_statement
            - financials_ttm
            - estimates_consensus
            - estimates_recommendations
            - dividends_history
            - news_stock
            - market_cap
          example: etf_profile
        params:
          type: object
          description: Additional parameters passed to every invocation. Merged with each symbol/ISIN entry. Use for shared parameters like date ranges.
          additionalProperties: true
          example: {}
    BulkResultItem:
      type: object
      description: Single result from a bulk invocation. Shape depends on the target endpoint. On failure, contains `valid`, `error`, and `message` fields.
      properties:
        symbol:
          type: string
          description: Echoed back from the request entry.
          example: AAPL
        isin:
          type: string
          description: Echoed back from the request entry.
          example: US0378331005
        valid:
          type: boolean
          description: Present and `false` when the invocation failed.
        error:
          type: string
          description: Error code (only on failure).
          example: LAMBDA_INVOCATION_FAILED
        message:
          type: string
          description: Error detail (only on failure).
      additionalProperties: true
    ForexCandle:
      type: object
      description: Forex OHLCV candle bar.
      required:
        - price
        - timestamp
      properties:
        price:
          type: number
          format: double
          description: Current price
          example: 1.1603
        change:
          type: number
          format: double
          nullable: true
          description: Price change
          example: -0.00054
        changesPercentage:
          type: number
          format: double
          nullable: true
          description: Price change as a percentage
          example: -0.04651804
        dayHigh:
          type: number
          format: double
          description: Intraday high price
          example: 1.16456
        dayLow:
          type: number
          format: double
          description: Intraday low price
          example: 1.15904
        open:
          type: number
          format: double
          description: Opening price
          example: 1.16084
        previousClose:
          type: number
          format: double
          nullable: true
          description: Previous session closing price
          example: 1.16084
        timestamp:
          type: string
          description: ISO 8601 timestamp
    CountryExposure:
      type: object
      description: Geographic country allocation with exposure percentage.
      required:
        - country
        - exposure
      properties:
        country:
          type: string
          description: Country name
          example: United States
        exposure:
          type: number
          format: double
          description: Exposure percentage
          example: 97.57
    DividendRecord:
      type: object
      description: 'A single dividend event. A future-dated record is a declared dividend that

        has not been paid yet.'
      required:
        - symbol
        - date
        - amount
      properties:
        symbol:
          type: string
          description: Ticker symbol
          example: AAPL
        isin:
          type: string
          nullable: true
          description: ISIN of the instrument, resolved from the symbol. Returned by /v2/dividends/calendar; null when the symbol does not map to a known security.
          example: US0378331005
        date:
          type: string
          format: date
          description: Dividend date
        adjustedAmount:
          type: number
          format: double
          description: Split-adjusted dividend per share
          example: 0.25
        amount:
          type: number
          format: double
          description: Actual payment per share
          example: 0.25
        recordDate:
          type: string
          format: date
          description: Dividend record date
        payDate:
          type: string
          format: date
          description: Dividend payment date
        declarationDate:
          type: string
          format: date
          nullable: true
          description: Dividend declaration date
        exDate:
          type: string
          nullable: true
          format: date
          description: Ex-dividend date
        currency:
          type: string
          nullable: true
          description: Currency code the amounts are quoted in. /v2/dividends/calendar returns null when the instrument's currency is unknown.
          example: USD
    Error:
      type: object
      description: 'Standard error response.


        Two 404 messages exist and they mean different things. "The requested

        security is not found." means the identifier did not resolve. "No data

        available for the requested security." means it resolved but has no data

        for this request.'
      properties:
        message:
          type: string
          description: Human-readable error description
          example: No data available for the requested security.
        status:
          type: string
          description: Error status indicator
          example: ERROR
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - message
        - status
    FinancialPeriodMeta:
      type: object
      description: SEC filing metadata attached to each financial statement period.
      properties:
        date:
          type: string
          format: date
          description: Period end date
          example: '2025-09-27'
        frequency:
          type: string
          enum:
            - annual
            - quarterly
          description: Reporting frequency
        reportedCurrency:
          type: string
          description: Currency of reported values (ISO 4217)
          example: USD
        cik:
          type: string
          description: SEC Central Index Key (10-digit)
          example: 320193
        filingDate:
          type: string
          format: date
          description: SEC filing submission date
        acceptedDate:
          type: string
          format: date-time
          description: SEC acceptance timestamp
        calendarYear:
          type: string
          description: Calendar year
          example: '2025'
        period:
          type: string
          description: 'Period code: FY, Q1, Q2, Q3, Q4'
          example: FY
        link:
          type: string
          format: uri
          description: SEC EDGAR filing index URL
        finalLink:
          type: string
          format: uri
          description: Direct SEC filing document URL
        isGapData:
          type: boolean
          nullable: true
          description: Whether this period was interpolated to fill a gap
    HoldingRecord:
      type: object
      description: Single ETF/fund holding.
      required:
        - name
        - percent
      properties:
        name:
          type: string
          nullable: true
          description: Holding name. Null when the constituent has no resolved master-record name yet; the key is always present.
          example: Apple Inc.
        symbol:
          type: string
          nullable: true
          description: Ticker symbol
          example: AAPL
        isin:
          type: string
          nullable: true
          description: ISIN identifier
        percent:
          type: number
          nullable: true
          format: double
          description: Weight (%) of net assets. With `view=display` (default) the market-value weight, so a fund's rows sum to ~100; swaps and futures without a market value and negative cash rows are left out (they are in `raw`). With `view=raw` a derivative's exposure weight (a 3x fund sums to ~300, an inverse fund's swaps are negative). Plain ETFs carry the same rows and weights in both views. Null only when the issuer publishes neither weight.
          example: 7.79
        value:
          type: number
          nullable: true
          format: double
          description: Issuer-reported position value in the source currency, which is not normalized here. Null when not reported. Use calculatedValue for an explicitly labelled USD estimate.
        share:
          type: number
          nullable: true
          format: double
          description: Shares held
        cusip:
          type: string
          nullable: true
          description: CUSIP identifier
        calculatedValue:
          type: object
          nullable: true
          description: Bavest-calculated USD estimate, separate from issuer-reported value. Only available for a currently matching equity position with no reported value.
          required:
            - value
            - currency
            - method
            - priceDate
            - fxDate
            - calculatedAt
          properties:
            value:
              type: number
              format: double
              description: Estimated position value in USD.
            currency:
              type: string
              enum:
                - USD
            method:
              type: string
              example: equity_quantity_times_historical_close_v1
            priceDate:
              type: string
              format: date
            fxDate:
              type: string
              format: date
            calculatedAt:
              type: string
              format: date-time
        holdingType:
          type: string
          nullable: true
          enum:
            - equity
            - swap
            - future
            - cash
            - money_market
            - treasury_bill
            - other
            - null
          description: Position type. `equity` for a listed security; swaps, futures, Treasury bills, money market funds and cash / net other assets are kept as their own rows (no ISIN); `other` for an unlisted instrument such as a bond. Null on issuer top-10 lists that publish names only.
          example: equity
        marketValue:
          type: number
          nullable: true
          format: double
          description: Issuer-reported market value in the source currency; the basis of `percent` in `view=display`. Null when the issuer publishes none (swaps, futures).
        exposureValue:
          type: number
          nullable: true
          format: double
          description: Issuer-reported exposure (notional plus gain/loss) of a swap or future, in the source currency; the basis of `percent` in `view=raw`. Null for positions without one.
          example: 9920928648.41
        counterparty:
          type: string
          nullable: true
          description: Swap counterparty as the issuer names it. Null for every other position.
          example: BNP Paribas
    SecurityListItem:
      type: object
      description: 'One exchange listing in a list endpoint (ADR, ETF, or stock). The list is listing-level, not instrument-level: the same ISIN appears once per exchange listing.'
      required:
        - name
      properties:
        isin:
          type: string
          description: ISIN identifier. Guaranteed to be ISO-6166-shaped, uppercase and trimmed; rows without a structurally valid ISIN are excluded.
          pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
          example: IE00B4L5Y983
        symbol:
          type: string
          description: Ticker symbol
          example: SPY
        name:
          type: string
          description: Security name. Null when no name has been resolved from any source yet; the key is always present.
          nullable: true
          example: SPDR S&P 500 ETF Trust
        country:
          type: string
          description: Country of domicile (ISO 3166-1 alpha-2)
          nullable: true
          example: US
        exchange:
          type: string
          description: Exchange name
          nullable: true
          example: NASDAQ Global Market
        exchangeCode:
          type: string
          description: Exchange short code
          nullable: true
          example: NASDAQ
        sector:
          type: string
          description: Industry sector
          nullable: true
          example: Technology
    DelistedSecurityListItem:
      type: object
      description: A delisted security (lifecycle status 'delisted').
      required:
        - name
      properties:
        isin:
          type: string
          description: ISIN identifier
          nullable: true
          example: IE000TLLSP66
        symbol:
          type: string
          description: Ticker symbol
          nullable: true
          example: YI
        name:
          type: string
          description: Security name
          example: 111, Inc.
        type:
          type: string
          description: Security type
          example: EQUITY
        exchange:
          type: string
          description: Exchange the security traded on
          nullable: true
          example: NASDAQ
        deprecatedAt:
          type: string
          format: date-time
          description: When the security was marked delisted (ISO-8601, tz-aware)
          nullable: true
          example: '2026-05-21T12:16:43.824829+00:00'
        deprecationReason:
          type: string
          description: Reason the row left active status
          nullable: true
          example: delisted
    IsinChangeListItem:
      type: object
      description: A security whose ISIN changed, with the old and new ISIN. The old row was deprecated (deprecation_reason 'isin_changed') and superseded by a new active row for the same instrument.
      required:
        - name
      properties:
        oldIsin:
          type: string
          description: Previous (deprecated) ISIN
          nullable: true
          example: US0079031078
        newIsin:
          type: string
          description: Current (successor) ISIN
          nullable: true
          example: US0079031115
        symbol:
          type: string
          description: Ticker symbol (the successor's, unchanged across an ISIN change)
          nullable: true
          example: AMD
        name:
          type: string
          description: Security name
          example: Advanced Micro Devices, Inc.
        type:
          type: string
          description: Security type
          example: EQUITY
        exchange:
          type: string
          description: Exchange the security trades on
          nullable: true
          example: NASDAQ
        changedAt:
          type: string
          format: date-time
          description: When the old row was deprecated / the ISIN change recorded (ISO-8601, tz-aware)
          nullable: true
          example: '2026-05-21T12:16:43.824829+00:00'
        deprecationReason:
          type: string
          description: Reason the old row left active status
          nullable: true
          example: isin_changed
    CryptoListItem:
      type: object
      description: A cryptocurrency in the crypto list.
      required:
        - symbol
        - name
      properties:
        symbol:
          type: string
          description: Cryptocurrency pair symbol
          example: AAVE-CAD
        name:
          type: string
          description: Cryptocurrency pair name
          example: Aave CAD
        cryptocurrency:
          type: string
          description: Base cryptocurrency ticker
          nullable: true
          example: AAVE
        currency:
          type: string
          description: Quote currency
          nullable: true
          example: CAD
    FundListItem:
      type: object
      description: A mutual fund in the fund list.
      required:
        - isin
        - name
      properties:
        isin:
          type: string
          description: Fund ISIN
          example: LU0342677829
        name:
          type: string
          description: Fund name
          example: AGIF - Allianz Global Equity Unconstrained - A - EUR
        fundCompany:
          type: string
          description: Fund management company
          nullable: true
          example: Allianz Global Investors GmbH
    SectorExposure:
      type: object
      description: Sector allocation with exposure percentage.
      required:
        - sector
        - exposure
      properties:
        sector:
          type: string
          description: Sector name
          example: Technology
        exposure:
          type: number
          format: double
          description: Exposure percentage
          example: 35.62
    ResponseMeta:
      type: object
      description: 'Response metadata, including server-side processing time and resolved request parameters. Successful and error responses use the same metadata shape.'
      properties:
        time:
          type: integer
          description: Server-side processing time in milliseconds
          example: 17
        parameters:
          type: object
          additionalProperties: true
          description: Echo of the request parameters the endpoint resolved
          example:
            symbol: AAPL
    PaginationMeta:
      type: object
      description: 'Response metadata for paginated endpoints. Offset pagination returns

        `page`/`pageSize`/`totalPages`/`totalCount`; cursor pagination returns

        `pageSize`/`hasMore`/`nextCursor` and `totalCount` only when known.'
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          properties:
            page:
              type: integer
              description: Current page number (offset pagination)
              example: 1
            pageSize:
              type: integer
              description: Number of results per page
              example: 50
            totalPages:
              type: integer
              description: Total number of pages (offset pagination)
              example: 2
            totalCount:
              type: integer
              description: Total number of results across all pages
              example: 100
            hasMore:
              type: boolean
              description: Whether more results follow (cursor pagination)
            nextCursor:
              type: string
              nullable: true
              description: Cursor for the next page (cursor pagination), null on the last page
    AGMRecord:
      type: object
      description: Annual General Meeting calendar record sourced from SEC DEF 14A filings.
      required:
        - meetingDate
        - symbol
      properties:
        meetingDate:
          type: string
          format: date
          description: Scheduled meeting date
          example: '2026-05-15'
        symbol:
          type: string
          description: Ticker symbol
          example: AAPL
        isin:
          type: string
          nullable: true
          description: ISIN identifier
          example: US0378331005
        recordDate:
          type: string
          format: date
          nullable: true
          description: Record date for shareholder eligibility
    EarningsCalendarRecord:
      type: object
      description: Earnings calendar event.
      properties:
        eventType:
          type: string
          description: Type of corporate event
          example: earnings
        date:
          type: string
          format: date
          description: Event date
          example: '2026-05-27'
        symbol:
          type: string
          description: Ticker symbol
          example: NVDA
        eps:
          type: number
          format: double
          nullable: true
          description: Actual earnings per share
          example: 0.89
        epsEstimated:
          type: number
          format: double
          nullable: true
          description: Estimated earnings per share
          example: 0.85
        revenue:
          type: number
          format: double
          nullable: true
          description: Actual revenue
          example: 44000000000
        revenueEstimated:
          type: number
          format: double
          nullable: true
          description: Estimated revenue
          example: 43500000000
        fiscalDateEnding:
          type: string
          format: date
          nullable: true
          description: Fiscal period end date
          example: '2026-04-30'
        time:
          type: string
          nullable: true
          description: Time of day (bmo = before market open, amc = after market close)
          enum:
            - bmo
            - amc
            - dmh
          x-enumDescriptions:
            bmo: Before market open
            amc: After market close
            dmh: During market hours
          example: bmo
    EarningsEvent:
      type: object
      description: Historical or upcoming earnings announcement with actual and estimated figures.
      properties:
        date:
          type: string
          format: date
          description: Event date
        epsActual:
          type: number
          format: double
          nullable: true
          description: Actual reported EPS
        epsEstimate:
          type: number
          format: double
          nullable: true
          description: Consensus EPS estimate
        epsSurprise:
          type: number
          format: double
          nullable: true
          description: EPS surprise (actual minus estimate)
        revenueActual:
          type: number
          format: double
          nullable: true
          description: Actual reported revenue
        revenueEstimate:
          type: number
          format: double
          nullable: true
          description: Consensus revenue estimate
    EarningsTranscript:
      type: object
      description: Earnings call transcript for a specific quarter.
      properties:
        date:
          type: string
          format: date
          description: Event date
        symbol:
          type: string
          description: Ticker symbol
        year:
          type: integer
          nullable: true
          description: Fiscal year
        quarter:
          type: integer
          nullable: true
          description: Fiscal quarter (1-4)
        content:
          type: string
          nullable: true
          description: Full earnings call transcript text
    SplitRecord:
      type: object
      description: Stock split event record.
      properties:
        date:
          type: string
          format: date
          description: Event date
          example: '2020-08-31'
        symbol:
          type: string
          description: Ticker symbol
          example: AAPL
        fromFactor:
          type: integer
          description: Original share count
          example: 1
        toFactor:
          type: integer
          description: New shares per original
          example: 4
    TranscriptPeriod:
      type: object
      description: Available year/quarter combination for earnings transcripts.
      properties:
        year:
          type: integer
          description: Fiscal year
          example: 2024
        quarter:
          type: integer
          description: Fiscal quarter (1-4)
          example: 3
    EconomyCountriesResponse:
      type: object
      description: List of countries with macroeconomic data available.
      properties:
        countries:
          type: array
          description: Countries with macroeconomic data, sorted by ISO-2 code.
          items:
            $ref: '#/components/schemas/EconomyCountry'
      required:
        - countries
    EconomyCountry:
      type: object
      description: A country with macroeconomic data available in the Bavest API.
      properties:
        iso2:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
        iso3:
          type: string
          description: ISO 3166-1 alpha-3 country code
          example: USA
        name:
          type: string
          description: Country display name
          example: United States
      required:
        - iso2
        - iso3
        - name
    EconomyIndicatorResponse:
      type: object
      description: Macroeconomic indicator data grouped by metric.
      properties:
        category:
          type: string
          nullable: true
          description: Metric category
          example: inflation
          enum:
            - business_confidence
            - consumer_confidence
            - consumer_spending
            - economic_sentiment
            - employment
            - gdp
            - government
            - housing
            - income
            - industrial_production
            - inflation
            - interest_rates
            - investment
            - manufacturing
            - money_supply
            - trade
        country:
          type: string
          nullable: true
          description: ISO 3166-1 alpha-2 country code
          example: US
        metrics:
          type: array
          description: Metrics matching the query, each with its own data array
          items:
            $ref: '#/components/schemas/EconomyMetric'
      required:
        - metrics
    EconomyMetricCode:
      type: string
      description: 'Machine-readable metric code identifying a macroeconomic indicator. Pass one of these values as the `metric` query parameter to `/v2/economy/indicator`.'
      enum:
        - BUSINESS_CONFIDENCE_EU
        - EXPORT_ORDERS
        - IFO_BUSINESS_CLIMATE
        - IFO_EXPECTATIONS
        - CONSUMER_CONFIDENCE_US
        - GFK_CONSUMER
        - UMICH_SENTIMENT
        - CONSUMER_EXPENDITURE
        - HOUSEHOLD_CONSUMPTION_WB
        - PCE
        - RETAIL_SALES
        - ZEW_SENTIMENT
        - CRUDE_OIL_IMPORTS
        - CRUDE_OIL_STOCKS
        - DISTILLATE_PRODUCTION
        - DISTILLATE_STOCKS
        - GASOLINE_STOCKS
        - REFINERY_CRUDE_RUNS
        - REFINERY_UTILIZATION
        - EMPLOYED_PERSONS
        - INITIAL_CLAIMS
        - JOB_OPENINGS
        - LABOR_FORCE_PARTICIPATION
        - LABOR_FORCE_WB
        - NONFARM_PAYROLLS
        - UNEMPLOYMENT_ILO
        - UNEMPLOYMENT_RATE
        - UNEMPLOYMENT_WB
        - GDP_GROWTH_WB
        - GDP_NOMINAL
        - GDP_NOMINAL_WB
        - GDP_PER_CAPITA_WB
        - GDP_REAL
        - GDP_REAL_WB
        - GOVT_CONSUMPTION
        - BUILDING_PERMITS
        - CONSTRUCTION_PRICE_INDEX
        - HOME_PRICE_INDEX
        - HOUSE_PRICE_INDEX
        - HOUSING_STARTS
        - NEW_HOME_SALES
        - AVG_HOURLY_EARNINGS
        - INCOME_STATISTICS
        - PERSONAL_INCOME
        - INDUSTRIAL_PRODUCTION
        - MANUFACTURING_IP
        - CPI
        - CPI_WB
        - CPI_CORE
        - GDP_DEFLATOR
        - HICP
        - HICP_CORE
        - HICP_CORE_INDEX
        - HICP_INDEX
        - INFLATION_WB
        - PCE_PRICE_INDEX
        - PPI
        - PPI_FINAL_DEMAND
        - BOC_RATE
        - BOE_RATE
        - BOJ_RATE
        - BOK_RATE
        - DE_10Y_YIELD
        - DE_3M_RATE
        - ECB_DFR
        - ECB_MRR
        - FED_FUNDS
        - PBOC_RATE
        - POLICY_RATE
        - RBA_RATE
        - BUSINESS_INVESTMENT
        - GROSS_CAPITAL_FORMATION_WB
        - PRIVATE_INVESTMENT
        - DURABLE_GOODS_ORDERS
        - M2_PCT_GDP_WB
        - MONEY_SUPPLY_M1
        - MONEY_SUPPLY_M2
        - MONEY_SUPPLY_M3
        - EXPORTS_GOODS_SERVICES
        - IMPORTS_GOODS_SERVICES
        - TRADE_BALANCE
        - WHOLESALE_TRADE
    EconomyMetric:
      type: object
      description: A macroeconomic metric with its time-series observations.
      properties:
        code:
          type: string
          description: Machine-readable metric code
          example: CPI
        name:
          type: string
          description: Human-readable metric name
          example: CPI All Urban Consumers
        frequency:
          type: string
          description: Data release frequency
          example: Monthly
        data:
          type: array
          description: Time-series observations, ordered by referencePeriod descending
          items:
            $ref: '#/components/schemas/EconomyMetricObservation'
        seriesCode:
          type: string
          description: Data source series identifier (e.g. CUUR0000SA0)
          example: CUUR0000SA0
        unit:
          type: string
          description: Measurement unit (e.g. PCT, INDEX_1982, USD_REAL_BN)
          example: INDEX_1982
      required:
        - code
        - name
        - data
    EconomyMetricObservation:
      type: object
      description: A single macroeconomic data point for a specific period.
      properties:
        referencePeriod:
          type: string
          format: date
          description: Observation date (YYYY-MM-DD)
          example: '2026-02-01'
        value:
          type: number
          nullable: true
          description: Observed value
          example: 326.785
      required:
        - referencePeriod
    CompanyProfile:
      type: object
      description: Company identity and classification. Equity-specific — no ETF/fund flags.
      required:
        - symbol
        - companyName
      properties:
        symbol:
          type: string
          description: Ticker symbol
          example: AAPL
        companyName:
          type: string
          description: Legal company name
          example: Apple Inc.
        description:
          type: string
          description: Business summary of the company
        ceo:
          type: string
          description: Chief Executive Officer name
          example: Timothy D. Cook
        sector:
          type: string
          description: GICS sector
          example: Technology
        industry:
          type: string
          description: GICS industry
          example: Consumer Electronics
        country:
          type: string
          description: ISO 3166-1 alpha-2
          example: US
        state:
          type: string
          description: State or province of headquarters
          example: CA
        city:
          type: string
          description: City of headquarters
          example: Cupertino
        address:
          type: string
          description: Street address of headquarters
          example: One Apple Park Way
        zip:
          type: string
          description: Postal or ZIP code
          example: '95014'
        phone:
          type: string
          description: Primary contact phone number
          example: (408) 996-1010
        website:
          type: string
          format: uri
          description: Company website URL
          example: https://www.apple.com
        exchange:
          type: string
          description: Full name of the listing exchange
          example: NASDAQ Global Select
        exchangeShortName:
          type: string
          description: Abbreviated exchange name
          example: NASDAQ
        isin:
          type: string
          description: International Securities Identification Number
          example: US0378331005
        cik:
          type: string
          nullable: true
          description: SEC Central Index Key
          example: 320193
        ipo:
          type: string
          format: date
          nullable: true
          description: Initial public offering date
          example: '1980-12-12'
        currency:
          type: string
          description: Primary trading currency (ISO 4217)
          example: USD
        employeeTotal:
          type: integer
          nullable: true
          description: Total number of employees
          example: 164000
        isActivelyTrading:
          type: boolean
          description: Whether the security is currently actively traded
          example: true
        isAdr:
          type: boolean
          description: Whether the security is an American Depositary Receipt
          example: false
        isReit:
          type:
            - boolean
            - 'null'
          description: 'Whether the company is a REIT (real estate investment trust): its

            industry starts with "REIT", e.g. Realty Income "REIT - Retail".

            Never true for ETFs or funds. `null` when no industry is known.'
          example: true
    EstimatePeriod:
      type: object
      description: Analyst consensus estimates for a single fiscal period.
      properties:
        date:
          type: string
          format: date
          description: 'Fiscal period end date. Same value as `fiscalYearEnd`; kept for

            existing clients. Do not read the year of this date as the fiscal

            year, use `fiscalYear`.'
          example: '2026-09-27'
        fiscalYearEnd:
          type: string
          format: date
          description: Last day of the fiscal year the estimates cover.
          example: '2027-01-25'
        fiscalYear:
          type: integer
          description: 'Fiscal year label as FactSet prints it. A fiscal year ending in

            January, or in the first seven days of February (52/53-week years),

            carries the year it started in: NVIDIA''s year ending 2027-01-25 is

            2026. Every other fiscal year carries the year it ends in (Toyota''s

            year ending 2026-03-31 is 2026).'
          example: 2026
        currency:
          type: string
          nullable: true
          description: 'ISO 4217 currency of all monetary values and EPS in this row: the

            company''s reporting currency, also on foreign listings (Toyota in JPY

            on Xetra and NYSE, ASML in EUR on NASDAQ). Null when no annual

            report is on file.'
          example: USD
        symbol:
          type: string
          description: Ticker symbol of the company.
          example: AAPL
        estimatedEbitAvg:
          type: number
          nullable: true
          format: double
          description: Consensus average EBIT estimate.
          example: 194822900000.0
        estimatedEbitHigh:
          type: number
          nullable: true
          format: double
          description: Highest EBIT estimate among analysts.
          example: 205228900000.0
        estimatedEbitLow:
          type: number
          nullable: true
          format: double
          description: Lowest EBIT estimate among analysts.
          example: 187009450000.0
        estimatedEbitdaAvg:
          type: number
          nullable: true
          format: double
          description: Consensus average EBITDA estimate.
          example: 209951540000.0
        estimatedEbitdaHigh:
          type: number
          nullable: true
          format: double
          description: Highest EBITDA estimate among analysts.
          example: 221165600000.0
        estimatedEbitdaLow:
          type: number
          nullable: true
          format: double
          description: Lowest EBITDA estimate among analysts.
          example: 201531340000.0
        estimatedEpsAvg:
          type: number
          nullable: true
          format: double
          description: Consensus average EPS estimate.
          example: 13.33
        estimatedEpsHigh:
          type: number
          nullable: true
          format: double
          description: Highest EPS estimate among analysts.
          example: 14.2556
        estimatedEpsLow:
          type: number
          nullable: true
          format: double
          description: Lowest EPS estimate among analysts.
          example: 12.635
        estimatedNetIncomeAvg:
          type: number
          nullable: true
          format: double
          description: Consensus average net income estimate.
          example: 200012610000.0
        estimatedNetIncomeHigh:
          type: number
          nullable: true
          format: double
          description: Highest net income estimate among analysts.
          example: 213900800000.0
        estimatedNetIncomeLow:
          type: number
          nullable: true
          format: double
          description: Lowest net income estimate among analysts.
          example: 189584490000.0
        estimatedRevenueAvg:
          type: number
          format: double
          nullable: true
          description: Consensus average revenue estimate.
          example: 581688000000.0
        estimatedRevenueHigh:
          type: number
          format: double
          nullable: true
          description: Highest revenue estimate among analysts.
          example: 612757500000.0
        estimatedRevenueLow:
          type: number
          format: double
          nullable: true
          description: Lowest revenue estimate among analysts.
          example: 558359200000.0
        estimatedSgaExpenseAvg:
          type: number
          format: double
          nullable: true
          description: Consensus average SGA expense estimate.
          example: 37438870000.0
        estimatedSgaExpenseHigh:
          type: number
          format: double
          nullable: true
          description: Highest SGA expense estimate among analysts.
          example: 39438578000.0
        estimatedSgaExpenseLow:
          type: number
          format: double
          nullable: true
          description: Lowest SGA expense estimate among analysts.
          example: 35937370000.0
        numberAnalystsEstimatedEps:
          type: integer
          nullable: true
          description: Number of analysts providing EPS estimates.
          example: 14
        numberAnalystsEstimatedRevenue:
          type: integer
          description: Number of analysts providing revenue estimates.
          nullable: true
    PriceTargetConsensus:
      type: object
      description: Analyst price target consensus for a security.
      required:
        - symbol
      properties:
        symbol:
          type: string
          description: Ticker symbol
          example: AAPL
        date:
          type: string
          format: date
          nullable: true
          description: Date of the price-target consensus snapshot
          example: '2025-09-27'
        targetHigh:
          type: number
          format: double
          nullable: true
          description: Highest analyst price target
          example: 325.0
        targetLow:
          type: number
          format: double
          nullable: true
          description: Lowest analyst price target
          example: 183.86
        targetConsensus:
          type: number
          format: double
          nullable: true
          description: Mean analyst price target
          example: 256.14
        targetMedian:
          type: number
          format: double
          nullable: true
          description: Median analyst price target
          example: 260.0
        currency:
          type: string
          nullable: true
          description: 'ISO 4217 currency the four target values are quoted in — the currency

            the listing itself trades in. Targets are served for US venues only,

            so this is USD today.'
          example: USD
    RecommendationRecord:
      type: object
      description: 'How many analysts currently hold each rating on the security, with the

        consensus label derived from that distribution. These are covering

        analysts, not rating changes found in the news: BMW (DE0005190003) reports

        23 here.'
      required:
        - buy
        - hold
        - sell
      properties:
        symbol:
          type: string
          description: Ticker symbol
          example: AAPL
        consensus:
          type: string
          description: Consensus recommendation label
          example: Buy
        date:
          type: string
          format: date
          description: Date of the recommendation snapshot.
        buy:
          type: integer
          description: Number of buy recommendations.
        strongBuy:
          type: integer
          description: Number of strong buy recommendations.
        hold:
          type: integer
          description: Number of hold recommendations.
        sell:
          type: integer
          description: Number of sell recommendations.
        strongSell:
          type: integer
          description: Number of strong sell recommendations.
    UpgradeDowngradeRecord:
      type: object
      description: 'Analyst rating changes for one security on one date.


        Individual rating actions are in `ratings[]`. The firm is `ratings[].gradingCompany`,

        the grades are `ratings[].newGrade` and `ratings[].previousGrade`.'
      required:
        - date
        - symbol
      properties:
        date:
          type: string
          format: date
          description: Date of the rating change.
        symbol:
          type: string
          description: Ticker symbol of the company.
          example: AAPL
        ratings:
          type: array
          description: Detailed list of individual rating entries.
          items:
            type: object
            properties:
              url:
                type: string
                nullable: true
                description: 'URL to the full rating article or report. Null since the switch

                  to the vendor''s grade endpoint, which serves no article.'
                deprecated: true
                example: https://www.streetinsider.com/Analyst+Comments/KeyBanc+Sidelined+on+Apple+%28AAPL%29%3A+%27don%27t+see+a+catalyst+with+the+stock+trading+in+line+with+its+historical+valuation%27/26148368.html
              title:
                type: string
                nullable: true
                description: 'Headline of the rating report. Null since the switch to the

                  vendor''s grade endpoint, which serves no article.'
                deprecated: true
                example: 'KeyBanc Sidelined on Apple (AAPL): ''don''t see a catalyst with the stock trading in line with its historical valuation'''
              action:
                type: string
                description: Rating action described in this entry.
                example: hold
              newGrade:
                type: string
                description: New rating grade assigned.
                example: Sector Weight
              previousGrade:
                type: string
                nullable: true
                description: Previous rating grade before the change.
                example: Sector Weight
              publishedDate:
                type: string
                description: ISO 8601 timestamp when the rating was published.
                example: '2026-03-12T09:50:00.000Z'
              gradingCompany:
                type: string
                description: Name of the firm that issued the rating.
                example: KeyBanc
              priceWhenPosted:
                type: number
                nullable: true
                description: 'Stock price when the rating was published. Null since the switch

                  to the vendor''s grade endpoint, which serves no price.'
                deprecated: true
                example: 260.81
    FilingIdentifiers:
      type: object
      description: All known identifier forms for the filer, so consumers can key on whichever one they use internally.
      properties:
        symbol:
          type: string
          nullable: true
          description: Ticker symbol
          example: AAPL
        isin:
          type: string
          nullable: true
          description: ISIN code
          example: US0378331005
        cusip:
          type: string
          nullable: true
          description: CUSIP code
          example: 37833100
        cik:
          type: string
          nullable: true
          description: SEC Central Index Key (10-digit, zero-padded)
          example: 320193
        lei:
          type: string
          nullable: true
          description: Legal Entity Identifier (GLEIF). Not populated for SEC-sourced filings.
    FilingExhibit:
      type: object
      description: A single exhibit attached to the filing.
      properties:
        type:
          type: string
          description: Exhibit type code
          example: EX-99.1
        url:
          type: string
          format: uri
          description: Exhibit document URL
          example: https://www.sec.gov/Archives/edgar/data/320193/000032019326000018/ex99_1.htm
        description:
          type: string
          nullable: true
          description: Human-readable exhibit description
          example: Press release
    FilingDocuments:
      type: object
      nullable: true
      description: Links to the filing's documents. `exhibits` (and therefore `press_release`, which is derived from it) is null until enrichment completes.
      properties:
        filing_index:
          type: string
          format: uri
          description: SEC EDGAR filing index page. Known as soon as the filing is detected, independent of enrichment stage.
          example: https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany
        press_release:
          type: string
          format: uri
          nullable: true
          description: URL of the press-release exhibit (EX-99.1), when one was identified during enrichment. Null until the filing is enriched.
        exhibits:
          type: array
          nullable: true
          description: Full exhibit list. Null until the filing is enriched.
          items:
            $ref: '#/components/schemas/FilingExhibit'
    FilingPeriod:
      type: object
      nullable: true
      description: The fiscal period the filing reports on. Null until the filing is enriched.
      properties:
        fiscal_year:
          type: integer
          nullable: true
          description: Fiscal year. Currently null.
          example: 2026
        fiscal_quarter:
          type: integer
          nullable: true
          description: Fiscal quarter (1-4). Currently null.
          example: 3
        period_end:
          type: string
          format: date
          nullable: true
          description: Period end date. Null when no matching earnings-calendar entry was found during enrichment.
          example: '2026-06-27'
    EarningsRelease:
      type: object
      description: 'A single earnings-release filing event.'
      required:
        - event_type
        - source
        - accession_number
        - filed_at
        - updated_at
      properties:
        event_type:
          type: string
          description: Event type discriminator. Always `earnings_release` on this endpoint; other `/v2/filings/*` endpoints use other values.
          example: earnings_release
        source:
          type: string
          enum:
            - sec_edgar
          description: Filing source registry. Currently `sec_edgar`.
          example: sec_edgar
        form_type:
          type: string
          description: Regulator form type of the underlying filing (e.g. `8-K`). Kept as a free string so non-SEC form types fit without a schema change.
          example: 8-K
        is_amendment:
          type: boolean
          description: True when this filing amends a prior filing.
          example: false
        amends_accession_number:
          type: string
          nullable: true
          description: Accession number of the filing this amends, or null when `is_amendment` is false.
        items:
          type: array
          nullable: true
          description: SEC 8-K item codes that triggered this event, e.g. `2.02` (Results of Operations and Financial Condition) or `9.01` (Financial Statements and Exhibits). Null when item codes are unavailable.
          items:
            type: string
          example:
            - '2.02'
            - '9.01'
        identifiers:
          $ref: '#/components/schemas/FilingIdentifiers'
        company_name:
          type: string
          nullable: true
          description: Filer's registered company name
          example: Apple Inc.
        accession_number:
          type: string
          description: SEC accession number (unique per filing)
          example: 0000320193-26-000018
        filed_at:
          type: string
          format: date-time
          description: Filing timestamp reported by SEC EDGAR (ISO-8601, UTC).
          example: '2026-07-30T20:30:28+00:00'
        updated_at:
          type: string
          format: date-time
          description: When this event row was last written (ISO-8601, UTC). Sort key for `updated_since` delta polling.
          example: '2026-07-30T20:30:36+00:00'
        report_date:
          type: string
          format: date
          nullable: true
          description: Reporting date as stated by the filer, when different from `filed_at`'s calendar date.
          example: '2026-07-30'
        headline:
          type: string
          nullable: true
          description: Short human-readable summary. Null until the filing is enriched.
          example: Apple reports third quarter results
        documents:
          $ref: '#/components/schemas/FilingDocuments'
        period:
          $ref: '#/components/schemas/FilingPeriod'
    EarningsReleaseList:
      type: object
      description: Cursor-paginated list of earnings-release events.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EarningsRelease'
        meta:
          type: object
          description: Cursor pagination metadata. No `totalCount` — computing an exact total across a firehose feed is not worth the query cost.
          properties:
            pageSize:
              type: integer
              description: Page size requested (echoes `limit`)
            hasMore:
              type: boolean
              description: Whether another page is available
            nextCursor:
              type: string
              nullable: true
              description: Opaque cursor for the next page, or null when `hasMore` is false
            time:
              type: integer
              description: Server-side processing time in milliseconds
              example: 17
            parameters:
              type: object
              additionalProperties: true
              description: Echo of the request parameters the endpoint resolved
    ForecastMeta:
      type: object
      description: Freshness summary for the returned forecast set.
      properties:
        as_of:
          type: string
          format: date
          description: Most recent prediction_date across the returned rows.
          example: '2026-05-20'
        model_version:
          type: string
          description: Model version of the newest returned row.
          example: fmf-eps-v1.4
    ForecastExplainability:
      type: object
      nullable: true
      description: Top contributing features for the prediction (SHAP), when available.
      properties:
        top_features:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Feature name.
                example: revenue_ttm
              shap:
                type: number
                format: double
                description: SHAP contribution.
                example: 0.42
    RegressionPrediction:
      type: object
      description: Regression task payload — point forecast, interval, and decomposition.
      properties:
        point:
          type: number
          format: double
          example: 2.41
        lower:
          type: number
          format: double
          example: 2.18
        upper:
          type: number
          format: double
          example: 2.65
        components:
          type: object
          description: Forecast decomposition (e.g. trend/seasonal).
          additionalProperties:
            type: number
            format: double
          example:
            trend: 2.3
            seasonal: 0.11
        direction:
          type: string
          nullable: true
          enum:
            - up
            - down
          description: Direction of the forecast against the trailing value. Null without a trailing value.
          example: up
        direction_score:
          type: number
          format: double
          nullable: true
          description: Forecast minus trailing value, in the metric's own unit (not normalized).
          example: 0.12
        nowcast:
          type: object
          nullable: true
          description: Intra-year breakdown for annual targets once quarters of the year are reported. Null otherwise.
          properties:
            method:
              type: string
              example: nowcast
            fiscal_year:
              type: integer
              description: Calendar year of the target (January to December), for every company. Kept under this name for existing clients; read `calendar_year`.
              example: 2026
            calendar_year:
              type: integer
              description: Calendar year of the target (January to December). MSFT 2026 is January to December 2026, not its fiscal year ending June 2026.
              example: 2026
            realized:
              type: boolean
              description: Whether the calendar year has closed.
            realized_sum:
              type: number
              format: double
              description: Sum of the reported quarters so far.
            realized_quarters:
              type: array
              items:
                type: string
                format: date
            remaining_quarters:
              type: array
              items:
                type: string
                format: date
            w_realized:
              type: number
              format: double
              description: Weight of the reported part of the year.
            seasonality_source:
              type: string
            model_annual:
              type: number
              format: double
              nullable: true
              description: Model estimate of the full-year figure.
            remaining_estimate:
              type: number
              format: double
              nullable: true
            override_delta:
              type: number
              format: double
              description: Net curated override applied.
            overrides:
              type: array
              items:
                $ref: '#/components/schemas/PredictionOverride'
            annual_actual:
              type: number
              format: double
              nullable: true
            notes:
              type: array
              items:
                type: string
    ClassificationPrediction:
      type: object
      description: Classification task payload — label, class probabilities, and conformal set.
      properties:
        label:
          type: string
          description: Predicted class label.
          example: up
        proba:
          type: object
          description: Per-class probabilities (sum to 1).
          additionalProperties:
            type: number
            format: double
          example:
            up: 0.71
            down: 0.29
        conformal_set:
          type: array
          description: Conformal prediction set at the configured coverage level.
          items:
            type: string
          example:
            - up
        calibration:
          type: string
          description: Calibration method applied to the probabilities.
          example: isotonic
    HazardPrediction:
      type: object
      description: Hazard task payload — event label, probabilities, and decision threshold.
      properties:
        label:
          type: string
          description: Hazard outcome label.
          example: no_cut
        proba:
          type: object
          description: Hazard probabilities.
          additionalProperties:
            type: number
            format: double
          example:
            cut: 0.08
            no_cut: 0.92
        threshold:
          type: number
          format: double
          description: Probability threshold used to assign the label.
          example: 0.3
    PredictionRecord:
      type: object
      description: A single model prediction for one metric and horizon.
      properties:
        symbol:
          type: string
          description: Ticker symbol (rows are self-describing).
          example: AAPL
        metric:
          type: string
          description: Forecast metric, e.g. eps, revenue, ebitda, dividend.
          example: eps
        task_type:
          type: string
          description: Prediction task type.
          enum:
            - regression
            - classification
            - sequence
            - hazard
          example: regression
        target_date:
          type: string
          format: date
          description: Period the forecast is for.
          example: '2026-09-30'
        prediction_date:
          type: string
          format: date
          description: Point-in-time the forecast was generated.
          example: '2026-05-20'
        model_version:
          type: string
          example: fmf-eps-v1.4
        frequency:
          type: string
          description: Reporting frequency of the target.
          example: quarterly
        prediction:
          description: 'Payload shape varies by task_type. Uses anyOf, not oneOf: the three

            variants overlap (all carry point/lower/upper) and nothing in the

            payload discriminates them, so oneOf rejected every real response.'
          anyOf:
            - $ref: '#/components/schemas/RegressionPrediction'
            - $ref: '#/components/schemas/ClassificationPrediction'
            - $ref: '#/components/schemas/HazardPrediction'
        explainability:
          $ref: '#/components/schemas/ForecastExplainability'
    PredictionsResponse:
      type: object
      description: Model predictions for a security.
      properties:
        meta:
          $ref: '#/components/schemas/ForecastMeta'
        predictions:
          type: array
          items:
            $ref: '#/components/schemas/PredictionRecord'
    DividendEstimate:
      type: object
      description: 'Per-share annual dividend estimate for one open fiscal year. `date` is Jan 1

        of the fiscal year the dividend is declared FOR; annual payers pay it the

        year after (`expected_payment_year`). `source` says what carried the

        estimate; the FMF model is served only where none of the other sources has a

        row. `lower`/`upper` are an 80% band. Amounts are in

        `currency`, the currency of the listing''s dividend line.'
      properties:
        date:
          type: string
          format: date
          description: Jan 1 of the fiscal year.
          example: '2026-01-01'
        fiscal_year:
          type: integer
          example: 2026
        fiscal_year_end:
          type: string
          format: date
          nullable: true
          example: '2026-12-31'
        expected_payment_year:
          type: integer
          nullable: true
          example: 2027
        amount:
          type: number
          format: double
          description: Dividend per share (point estimate, or the declared amount).
          example: 3.49
        lower:
          type: number
          format: double
          description: Lower bound (10th percentile).
          example: 2.37
        upper:
          type: number
          format: double
          description: Upper bound (90th percentile).
          example: 5.24
        basis:
          type: string
          enum:
            - estimate
            - declared
          description: declared once the fiscal year's payments are in the dividend calendar.
          example: estimate
        is_estimate:
          type: boolean
          description: false when basis is declared.
          example: true
        source:
          type: string
          enum:
            - payout_policy
            - consensus_model
            - dividend_trend
            - fmf
          description: 'What carried the estimate. payout_policy: EPS consensus x the company''s

            stated payout corridor. consensus_model: declared dividend grown on the EPS

            consensus. dividend_trend: no analyst coverage, the company''s own dividend

            run-rate and trend. fmf: the FMF model.'
          example: consensus_model
        payout_ratio:
          type: number
          format: double
          nullable: true
          description: Implied payout (amount / EPS consensus) where dividend and EPS share a currency.
          example: 0.45
        currency:
          type: string
          nullable: true
          description: Currency of the listing's dividend line (GBp for London lines).
          example: EUR
        model:
          type: object
          nullable: true
          description: The FMF model estimate for the same year next to a consensus_model estimate.
          properties:
            amount:
              type: number
              format: double
            lower:
              type: number
              format: double
            upper:
              type: number
              format: double
    DividendEstimatesResponse:
      type: object
      description: Bavest's own per-share dividend forecast, newest first.
      properties:
        meta:
          type: object
          properties:
            as_of:
              type: string
              format: date
              description: Newest estimate date in the set.
              example: '2027-01-01'
            years:
              type: integer
              description: Number of fiscal years returned.
              example: 3
        estimates:
          type: array
          items:
            $ref: '#/components/schemas/DividendEstimate'
    PredictionOverride:
      type: object
      description: A curated adjustment applied on top of the model.
      properties:
        reason:
          type: string
          example: signed supply deal
        value:
          type: number
          format: double
          example: 10.0
    PredictionSnapshotDetail:
      type: object
      description: A forecast snapshot with its nowcast decomposition.
      properties:
        prediction_date:
          type: string
          format: date
          example: '2026-08-01'
        model_version:
          type: string
          nullable: true
          example: fmf-revenue-ensemble-v2
        point:
          type: number
          format: double
          example: 105.0
        lower:
          type: number
          format: double
          example: 95.0
        upper:
          type: number
          format: double
          example: 115.0
        realized:
          type: boolean
          nullable: true
          example: false
        realized_sum:
          type: number
          nullable: true
          format: double
          description: Sum of realized (reported) quarters to date.
          example: 45.0
        model_annual:
          type: number
          nullable: true
          format: double
          description: Model estimate of the full-year figure.
          example: 100.0
        override_delta:
          type: number
          nullable: true
          format: double
          description: Net curated override applied.
          example: 10.0
        overrides:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PredictionOverride'
    PredictionRevision:
      type: object
      description: A consecutive change between two snapshots, attributed to its drivers.
      properties:
        from_date:
          type: string
          format: date
          example: '2026-05-01'
        to_date:
          type: string
          format: date
          example: '2026-08-01'
        from_point:
          type: number
          format: double
          example: 95.0
        to_point:
          type: number
          format: double
          example: 105.0
        delta:
          type: number
          format: double
          example: 10.0
        drivers:
          type: object
          description: Attribution of the delta — realized quarters, curated overrides, and the residual model re-estimate (reconciles to delta).
          properties:
            realized:
              type: number
              format: double
              example: 25.0
            override:
              type: number
              format: double
              example: 10.0
            model:
              type: number
              format: double
              example: -25.0
    PredictionSnapshot:
      type: object
      description: A point in the snapshot series, with the same optional detail as `current`.
      properties:
        prediction_date:
          type: string
          format: date
          example: '2026-02-01'
        model_version:
          type: string
          nullable: true
          example: fmf-revenue-ensemble-v2
        point:
          type: number
          format: double
          example: 100.0
        lower:
          type: number
          format: double
          nullable: true
          example: 90.0
        upper:
          type: number
          format: double
          nullable: true
          example: 110.0
        realized:
          type: boolean
          nullable: true
          example: false
        realized_sum:
          type: number
          nullable: true
          format: double
          description: Sum of realized (reported) quarters to date.
        model_annual:
          type: number
          nullable: true
          format: double
          description: Model estimate of the full-year figure.
        override_delta:
          type: number
          nullable: true
          format: double
          description: Net curated override applied.
        overrides:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PredictionOverride'
    PredictionHistoryTarget:
      type: object
      description: Revision history for one target fiscal year.
      properties:
        target_date:
          type: string
          format: date
          example: '2026-12-31'
        fiscal_year:
          type: integer
          description: Calendar year of the target (January to December), for every company. Kept under this name for existing clients; read `calendar_year`.
          example: 2026
        calendar_year:
          type: integer
          description: Calendar year of the target (January to December).
          example: 2026
        realized:
          type: boolean
          description: Whether the calendar year has closed.
          example: false
        actual:
          type: number
          format: double
          nullable: true
          description: Realized actual once the year closes.
          example: null
        current:
          $ref: '#/components/schemas/PredictionSnapshotDetail'
        previous:
          description: Previous snapshot; null until at least one revision exists.
          anyOf:
            - $ref: '#/components/schemas/PredictionSnapshotDetail'
            - type: 'null'
        revisions:
          type: array
          items:
            $ref: '#/components/schemas/PredictionRevision'
        snapshots:
          type: array
          description: Full snapshot series, oldest first.
          items:
            $ref: '#/components/schemas/PredictionSnapshot'
    PredictionHistoryResponse:
      type: object
      description: How a security's forecast for one metric evolved over time.
      properties:
        metric:
          type: string
          example: revenue
        targets:
          type: array
          items:
            $ref: '#/components/schemas/PredictionHistoryTarget'
    ETFCategory:
      type: object
      description: ETF classification and categorization.
      required:
        - assetClass
      properties:
        assetClass:
          type: string
          description: Broad asset class (e.g. Equity, Fixed Income, Commodity)
          example: Equity
        category:
          type: string
          description: Investment category within the asset class (e.g. U.S. Equity)
          example: U.S. Equity
        focus:
          type: string
          description: Investment focus or strategy (e.g. Broad Market, Growth, Value)
          example: Broad Market
        niche:
          type: string
          description: Specific niche or investment approach (e.g. Index Tracking)
          example: Index Tracking
        index:
          type: string
          description: 'Name of the tracked index as published by the issuer. Same value as `indice` on `/v2/etfs/profile`: free text, not normalised, either the index family (`MSCI World`) or the full variant (`STOXX Europe 600 NR EUR`). Intended for display; do not join or filter on it.'
          nullable: true
          example: MSCI World
    ETFCountryExposure:
      type: object
      description: 'Geographic country allocation for an ETF, with exposure percentage.'
      required:
        - country
        - exposure
      properties:
        country:
          type: string
          description: Country name
          example: United States
        exposure:
          type: number
          format: double
          description: Exposure percentage
          example: 97.57
        synthetic:
          type: boolean
          default: false
          description: '`true` when the row is Bavest-generated rather than scraped from an

            issuer breakdown. Applies to products with no published geographic

            allocation to scrape — chiefly crypto and commodity funds.'
          example: false
    ETFSectorExposure:
      type: object
      description: 'Sector allocation for an ETF, with exposure percentage.


        Distinct from the shared `SectorExposure` schema, which the funds

        endpoints still use: ETF sector rows additionally record whether a row

        was generated by Bavest rather than scraped.'
      required:
        - sector
        - exposure
      properties:
        sector:
          type: string
          description: Sector name
          example: Technology
        exposure:
          type: number
          format: double
          description: Exposure percentage
          example: 35.62
        synthetic:
          type: boolean
          default: false
          description: '`true` when the row is Bavest-generated rather than scraped from an

            issuer breakdown. Applies to products with no published sector

            allocation to scrape — chiefly crypto and commodity funds.'
          example: false
    ETFFees:
      type: object
      description: ETF fee and expense information.
      properties:
        managementFee:
          type: number
          format: double
          description: Annual management fee as a decimal (e.g. 0.0045 = 0.45%)
          nullable: true
        performanceFee:
          type: number
          format: double
          description: Performance-based fee as a decimal, if applicable
          nullable: true
        netExpenseRatio:
          type: number
          format: double
          description: Net expense ratio after fee waivers, as a decimal (e.g. 0.002 = 0.2%)
          example: 0.2
        totalExpenseRatio:
          type: number
          format: double
          description: Total (gross) expense ratio as a decimal
    ETFMetricItem:
      type: object
      description: A single ETF metric value with optional computation lineage.
      required:
        - metricId
        - metricName
        - value
        - valid
      properties:
        metricId:
          type: string
          description: Machine-readable metric identifier (lowercase, e.g. beta_3y, return_1y)
          example: beta_3y
        metricName:
          type: string
          description: Metric name (uppercase)
          example: BETA_3Y
        date:
          type: string
          format: date
          nullable: true
          description: Observation date of this metric value
          example: '2026-03-31'
        value:
          type: number
          format: double
          nullable: true
          description: Computed metric value. Null when computation failed.
          example: 1.03
        valid:
          type: boolean
          description: Whether the metric was successfully computed
          example: true
        unit:
          type: string
          nullable: true
          description: Unit of measurement (MetricUnitModel value, uppercase)
          example: RATIO
        currency:
          type: string
          nullable: true
          description: Currency code if the metric is currency-denominated (null for ratios/percentages)
        trace:
          type: object
          nullable: true
          description: Computation lineage (only included when trace=true is passed)
          properties:
            formula:
              type: string
              nullable: true
              description: Formula template used for computation
              example: cov(R_etf, R_bench) / var(R_bench)
            formula_computed:
              type: string
              nullable: true
              description: Formula with actual computed values substituted
            inputs:
              type: object
              nullable: true
              description: Input values used in the calculation
              additionalProperties: true
              example:
                period: 3Y
                benchmark: ^GSPC
                beta: 1.03
            explanation:
              type: string
              nullable: true
              description: Natural language explanation of the computation result
              example: 'Beta (3Y) = 1.03 for 3Y vs ^GSPC. Inputs: beta=1.0300'
    ETFPerformanceMetrics:
      type: object
      deprecated: true
      description: '**Deprecated** — use /v2/etfs/metrics with the paginated ETFMetricItem response instead.

        Legacy ETF return and risk-adjusted performance across time horizons.'
      required:
        - symbol
      properties:
        symbol:
          type: string
          description: ETF ticker symbol
        oneMonth:
          type: number
          format: double
          nullable: true
          description: 1-month total return (decimal)
        threeMonth:
          type: number
          format: double
          nullable: true
          description: 3-month total return (decimal)
        sixMonth:
          type: number
          format: double
          nullable: true
          description: 6-month total return (decimal)
        ytd:
          type: number
          format: double
          nullable: true
          description: Year-to-date total return (decimal)
        oneYear:
          type: number
          format: double
          nullable: true
          description: 1-year total return (decimal)
        threeYear:
          type: number
          format: double
          nullable: true
          description: 3-year annualized return (decimal)
        fiveYear:
          type: number
          format: double
          nullable: true
          description: 5-year annualized return (decimal)
        tenYear:
          type: number
          format: double
          nullable: true
          description: 10-year annualized return (decimal)
        aum:
          type: number
          format: double
          description: Assets under management in fund currency
          example: 572926853120.0
    ETFProfile:
      type: object
      description: 'Core ETF identity and classification.


        Every property is always present in the response; any value may be `null`

        where the issuer does not publish it. `cusip` and `website` may also be an

        empty string for non-US listings.'
      required:
        - name
      properties:
        symbol:
          type: string
          nullable: true
          description: ETF ticker symbol
          example: ARKK
        isin:
          type: string
          nullable: true
          description: ETF ISIN code
          example: IE00B4L5Y983
        name:
          type: string
          nullable: true
          description: Official ETF name
          example: ARK Innovation ETF
        description:
          type: string
          nullable: true
          description: Brief description of the ETF's investment objective
        website:
          type: string
          nullable: true
          description: URL of the ETF issuer's product page, empty string if unknown
        domicile:
          type: string
          nullable: true
          description: Country of domicile (ISO 3166-1 alpha-2 code)
          example: IE
        inceptionDate:
          type: string
          nullable: true
          description: Date the ETF was launched
          format: date
        etfCompany:
          type: string
          nullable: true
          description: Name of the ETF issuer or management company
          example: ARK Invest
        assetClass:
          type: string
          nullable: true
          description: Broad asset class (e.g. Equity, Fixed Income, Commodity)
          example: Equity
        cusip:
          type: string
          nullable: true
          description: CUSIP identifier for the ETF, empty string for non-US listings
          example: 78462F103
        distributionPolicy:
          type: string
          description: Distribution policy (e.g. Accumulating, Distributing)
          nullable: true
        etfCategory:
          type: string
          nullable: true
          description: Investment category within the asset class
          example: U.S. Equity
        etfFocus:
          type: string
          nullable: true
          description: Investment focus or strategy
          example: Broad Market
        etfNiche:
          type: string
          nullable: true
          description: Specific niche or investment approach
          example: Index Tracking
        indice:
          type: string
          description: 'Name of the tracked index as published by the issuer. Free text, not normalised: either the index family alone (`S&P 500®`, `MSCI World`) or the full index variant with return type, currency and hedging (`STOXX Europe 600 NR EUR`, `S&P 500® ESG Elite (EUR Hedged)`). Suffixes are part of the official index name: PR/NR/TR = price, net total return, gross total return; EUR/USD = index currency; `Hedged` = currency-hedged variant. Null for actively managed ETFs or when the index is not captured. Intended for display; do not join or filter on it.'
          nullable: true
          example: STOXX Europe 600 NR EUR
        replicationMethod:
          type: string
          description: Index replication method (e.g. Full, Sampling, Synthetic)
          nullable: true
    ETFRisk:
      type: object
      description: ETF risk metrics across time horizons.
      required:
        - symbol
      properties:
        betaOneYear:
          type: number
          format: double
          description: 1-year beta relative to the benchmark
          nullable: true
        betaThreeYears:
          type: number
          format: double
          description: 3-year beta relative to the benchmark
          nullable: true
        betaFiveYears:
          type: number
          format: double
          description: 5-year beta relative to the benchmark
          nullable: true
        sri:
          type: integer
          nullable: true
          description: Summary Risk Indicator (1-7)
          minimum: 1
          maximum: 7
        srri:
          type: integer
          nullable: true
          description: Synthetic Risk and Reward Indicator (1-7)
          minimum: 1
          maximum: 7
        trackingError:
          type: number
          format: double
          description: Annualized tracking error versus the benchmark
          nullable: true
        volatility:
          type: number
          format: double
          description: Annualized price volatility (standard deviation of returns)
          nullable: true
        symbol:
          type: string
          description: ETF ticker symbol
          example: SPY
    ETFStructure:
      type: object
      description: ETF structural classification.
      required:
        - type
      properties:
        type:
          type: string
          description: Product type (e.g. ETF, ETC, ETN)
          example: ETF
        isBenchmark:
          type: boolean
          description: Whether the ETF serves as a benchmark
        isIndexTracked:
          type: boolean
          description: Whether the ETF tracks an index
        isLeveraged:
          type: boolean
          description: Whether the ETF uses leverage
        isComplex:
          type: boolean
          description: Whether the ETF is classified as a complex product
        isStructured:
          type: boolean
          description: Whether the ETF is a structured product
    ETFDocumentCatalogItem:
      type: object
      description: A single ETF document entry in the catalog.
      required:
        - isin
        - language
        - type
        - download_path
      properties:
        isin:
          type: string
          nullable: true
          description: ETF ISIN code
          example: IE00B4L5Y983
        language:
          type: string
          description: ISO 639-1 language code
          example: en
        type:
          type: string
          description: Document type
          enum:
            - KID
            - KIID
        download_path:
          type: string
          description: API path to download the document via /v2/etfs/kid
          example: /v2/etfs/kid?isin=IE00B4L5Y983&language=en
    BalanceSheet:
      type: object
      description: Balance sheet line items for a single reporting period.
      allOf:
        - $ref: '#/components/schemas/FinancialPeriodMeta'
        - type: object
          properties:
            cashAndCashEquivalents:
              type: number
              format: double
              description: Cash and cash equivalents
            shortTermInvestments:
              type: number
              format: double
              description: Short-term investments
            cashShortTermInvestments:
              type: number
              format: double
              description: Cash + short-term investments (derived)
            inventory:
              type: number
              format: double
              description: Inventory
            otherCurrentAssets:
              type: number
              format: double
              description: Other current assets
            currentAssets:
              type: number
              format: double
              description: Total current assets (derived)
            totalReceivables:
              type: number
              format: double
              description: Total receivables
            propertyPlantEquipment:
              type: number
              format: double
              description: PP&E net of depreciation
            goodwill:
              type: number
              format: double
              description: Goodwill
            intangibleAssets:
              type: number
              format: double
              description: Intangible assets
            goodwillAndIntangibleAssets:
              type: number
              format: double
              description: Goodwill + intangibles
            longTermInvestments:
              type: number
              format: double
              description: Long-term investments
            taxAssets:
              type: number
              format: double
              description: Tax assets
            otherNonCurrentAssets:
              type: number
              format: double
              description: Other non-current assets
            totalNonCurrentAssets:
              type: number
              format: double
              description: Total non-current assets
            otherAssets:
              type: number
              format: double
              description: Other assets
            totalInvestments:
              type: number
              format: double
              description: Total investments
            totalAssets:
              type: number
              format: double
              description: Total assets
            accountsPayable:
              type: number
              format: double
              description: Accounts payable
            shortTermDebt:
              type: number
              format: double
              description: Short-term debt
            taxPayables:
              type: number
              format: double
              description: Tax payables
            deferredRevenue:
              type: number
              format: double
              description: Deferred revenue (current)
            otherCurrentLiabilities:
              type: number
              format: double
              description: Other current liabilities
            currentLiabilities:
              type: number
              format: double
              description: Total current liabilities
            longTermDebt:
              type: number
              format: double
              description: Long-term debt
            deferredRevenueNonCurrent:
              type: number
              format: double
              description: Deferred revenue (non-current)
            deferredTaxLiabilitiesNonCurrent:
              type: number
              format: double
              description: Deferred tax liabilities
            otherNonCurrentLiabilities:
              type: number
              format: double
              description: Other non-current liabilities
            totalNonCurrentLiabilities:
              type: number
              format: double
              description: Total non-current liabilities
            otherLiabilities:
              type: number
              format: double
              description: Other liabilities
            capitalLeaseObligations:
              type: number
              format: double
              description: Capital lease obligations
            totalLiabilities:
              type: number
              format: double
              description: Total liabilities
            totalDebt:
              type: number
              format: double
              description: Total debt (short + long term)
            netDebt:
              type: number
              format: double
              description: Net debt (debt minus cash)
            preferredStock:
              type: number
              format: double
              description: Preferred stock
            commonStock:
              type: number
              format: double
              description: Common stock
            retainedEarnings:
              type: number
              format: double
              description: Retained earnings
            otherTotalStockholdersEquity:
              type: number
              format: double
              description: Other stockholders' equity
            totalStockholdersEquity:
              type: number
              format: double
              description: Total stockholders' equity
            minorityInterest:
              type: number
              format: double
              description: Minority interest
            totalEquity:
              type: number
              format: double
              description: Total equity
            totalLiabilitiesAndTotalEquity:
              type: number
              format: double
              description: Total liabilities + equity (= totalAssets)
            liabilitiesShareholdersEquity:
              type: number
              format: double
              description: Total liabilities and shareholders' equity
            otherEquity:
              type: number
              format: double
              description: Other equity components
    CashFlowStatement:
      type: object
      description: Cash flow statement line items for a single reporting period.
      allOf:
        - $ref: '#/components/schemas/FinancialPeriodMeta'
        - type: object
          properties:
            netIncome:
              type: number
              format: double
              description: Net income
            depreciationAmortization:
              type: number
              format: double
              description: Depreciation and amortization
            stockBasedCompensation:
              type: number
              format: double
              description: Stock-based compensation
            accountsReceivables:
              type: number
              format: double
              description: Change in accounts receivables
            inventory:
              type: number
              format: double
              description: Change in inventory
            accountsPayables:
              type: number
              format: double
              description: Change in accounts payables
            deferredTaxesInvestmentTaxCredit:
              type: number
              format: double
              description: Deferred taxes
            otherNonCashItems:
              type: number
              format: double
              description: Other non-cash items
            changesInWorkingCapital:
              type: number
              format: double
              description: Total working capital changes
            otherWorkingCapital:
              type: number
              format: double
              description: Other working capital items
            netCashProvidedByOperatingActivities:
              type: number
              format: double
              description: Net operating cash flow
            capex:
              type: number
              format: double
              description: Capital expenditures (negative)
            investmentsInPropertyPlantAndEquipment:
              type: number
              format: double
              description: PP&E investments
            acquisitionsNet:
              type: number
              format: double
              description: Net acquisitions
            purchasesOfInvestments:
              type: number
              format: double
              description: Investment purchases (negative)
            salesMaturitiesOfInvestments:
              type: number
              format: double
              description: Investment sales (positive)
            otherInvestingActivities:
              type: number
              format: double
              description: Other investing activities
            netInvestingCashFlow:
              type: number
              format: double
              description: Net investing cash flow
            commonStockIssued:
              type: number
              format: double
              description: Stock issuance proceeds
            issuanceReductionCapitalStock:
              type: number
              format: double
              description: Net buybacks (negative for repurchases)
            debtRepayment:
              type: number
              format: double
              description: Debt repayment (negative)
            cashDividendsPaid:
              type: number
              format: double
              description: Dividends paid (negative)
            otherFinancingActivities:
              type: number
              format: double
              description: Other financing activities
            netCashFinancingActivities:
              type: number
              format: double
              description: Net financing cash flow
            effectOfForexChangesOnCash:
              type: number
              format: double
              description: FX impact on cash
            changeInCash:
              type: number
              format: double
              description: Net change in cash
            cashAtBeginningOfPeriod:
              type: number
              format: double
              description: Opening cash balance
            cashAtEndOfPeriod:
              type: number
              format: double
              description: Closing cash balance
            netOperatingCashFlow:
              type: number
              format: double
              description: Net operating cash flow (alias)
            freeCashFlow:
              type: number
              format: double
              description: Free cash flow (operating - capex)
    StatementProvenance:
      type: object
      description: 'Present only when provenance=true. Keyed by statement date, one entry per row served in `financials`, answering when we got each statement and whether it changed since. Clients must tolerate unknown enum values and additional fields.'
      additionalProperties:
        type: object
        properties:
          source:
            type: string
            enum:
              - vendor
            description: Source of the statement values. Currently `vendor`. Clients should tolerate unknown values.
          knownAt:
            type: string
            format: date-time
            nullable: true
            description: When the currently served statement became known to Bavest. Null when observation history is unavailable for this security.
          firstKnownAt:
            type: string
            format: date-time
            nullable: true
            description: When we first observed any version of this statement.
          restated:
            type: boolean
            description: True when more than one distinct version of this statement has been observed for the period. Per statement — income statement, balance sheet and cash flow are tracked separately.
          acceptedDate:
            type: string
            format: date-time
            nullable: true
            description: Vendor-reported acceptance date. For non-SEC filings, this date may match the period end and is not a reliable filing timestamp. It does not indicate when the data became available to Bavest; use `knownAt` when available.
          filingDate:
            type: string
            format: date
            nullable: true
            description: Vendor-reported filing date. For non-SEC filings, this date may match the period end and is not a reliable filing timestamp. It does not indicate when the data became available to Bavest; use `knownAt` when available.
          filing:
            nullable: true
            description: Currently null.
          fields:
            nullable: true
            description: Currently null.
    IncomeStatement:
      type: object
      description: Income statement line items for a single reporting period.
      allOf:
        - $ref: '#/components/schemas/FinancialPeriodMeta'
        - type: object
          properties:
            revenue:
              type: number
              format: double
              description: Total revenue
            costOfGoodsSold:
              type: number
              format: double
              description: Cost of goods sold
            grossIncome:
              type: number
              format: double
              description: Gross income (revenue - COGS)
            grossProfitRatio:
              type: number
              format: double
              description: Gross profit margin (0-1 decimal)
            researchDevelopment:
              type: number
              format: double
              description: R&D expenses
            sgaExpense:
              type: number
              format: double
              description: SG&A expenses
            generalAndAdministrativeExpenses:
              type: number
              format: double
              description: G&A expenses
            sellingAndMarketingExpenses:
              type: number
              format: double
              description: Sales & marketing expenses
            totalOperatingExpense:
              type: number
              format: double
              description: Total operating expenses
            costAndExpenses:
              type: number
              format: double
              description: Total costs and expenses
            ebit:
              type: number
              format: double
              description: Earnings before interest & taxes
            ebitda:
              type: number
              format: double
              description: EBITDA
            ebitdaRatio:
              type: number
              format: double
              description: EBITDA / Revenue
            operatingIncomeRatio:
              type: number
              format: double
              description: Operating margin
            interestIncome:
              type: number
              format: double
              description: Interest income
            interestExpense:
              type: number
              format: double
              description: Interest expense
            totalOtherIncomeExpensesNet:
              type: number
              format: double
              description: Other income/expenses
            pretaxIncome:
              type: number
              format: double
              description: Pre-tax income
            incomeBeforeTaxRatio:
              type: number
              format: double
              description: Pre-tax margin
            provisionForIncomeTaxes:
              type: number
              format: double
              description: Tax provision
            netIncome:
              type: number
              format: double
              description: Net income
            netIncomeRatio:
              type: number
              format: double
              description: Net income margin
            eps:
              type: number
              format: double
              description: Basic EPS
            dilutedEps:
              type: number
              format: double
              description: Diluted EPS
            weightedAverageShsOut:
              type: number
              format: double
              description: Weighted average shares outstanding
            dilutedAverageSharesOutstanding:
              type: number
              format: double
              description: Diluted average shares outstanding
            depreciationAndAmortization:
              type: number
              format: double
              description: D&A expense
            otherExpenses:
              type: number
              format: double
              description: Other expenses
    EquityMetrics:
      type: object
      description: Comprehensive equity metrics response with per-metric metadata.
      properties:
        latestDate:
          type: string
          format: date
          nullable: true
          description: Most recent observation date across all metrics
          example: '2025-09-27'
        metrics:
          type: array
          description: Array of individual metric entries
          items:
            type: object
            properties:
              metricId:
                type: string
                description: Metric identifier (camelCase)
                example: peRatio
              date:
                type: string
                format: date
                nullable: true
                description: Observation date of this metric value
                example: '2025-09-27'
              metricName:
                type: string
                description: Raw metric name from the data source
                example: pe_ratio
              value:
                type: number
                format: double
                nullable: true
                description: Metric value (null if unavailable)
                example: 32.13
              valid:
                type: boolean
                description: Whether the metric value is available
                example: true
              reason:
                type: string
                nullable: true
                description: Reason if value is null or flagged
              rootCause:
                type: string
                nullable: true
                description: Root cause for null or anomalous values
              description:
                type: string
                nullable: true
                description: Human-readable metric description
                example: Price to earnings ratio
              unit:
                type: string
                nullable: true
                description: Metric unit (e.g., ratio, USD, percent)
                example: ratio
              currency:
                type: string
                nullable: true
                description: Currency of monetary values (ISO 4217)
                example: USD
    MetricsLatestResponse:
      type: object
      description: Latest macroeconomic metric observations, grouped by metric code.
      properties:
        category:
          type: string
          nullable: true
          description: Metric category (e.g. inflation, gdp, employment, interest_rates)
          example: inflation
        as_of:
          type: string
          format: date
          description: Snapshot date for the observations (defaults to today)
          example: '2026-03-31'
        countries:
          type: array
          description: ISO 3166-1 alpha-2 country codes present in the response
          items:
            type: string
          example:
            - US
            - DE
        metrics:
          type: array
          description: Metrics matching the query, each with its own data array
          items:
            $ref: '#/components/schemas/MetricsLatestMetric'
    MetricsLatestMetric:
      type: object
      description: A macroeconomic metric with its latest observations across countries.
      required:
        - code
        - data
      properties:
        code:
          type: string
          description: Machine-readable metric code
          example: CPI
        name:
          type: string
          nullable: true
          description: Human-readable metric name
          example: CPI All Urban Consumers
        frequency:
          type: string
          nullable: true
          description: Data release frequency (e.g. Monthly, Quarterly, Annual)
          example: Monthly
        data:
          type: array
          description: Latest observations, one per country
          items:
            $ref: '#/components/schemas/MetricsLatestObservation'
    MetricsLatestObservation:
      type: object
      description: A single latest-value observation for a metric in a specific country.
      required:
        - country
        - value
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
        reference_period:
          type: string
          format: date
          nullable: true
          description: Reference period for the observation (YYYY-MM-DD)
          example: '2026-02-01'
        value:
          type: number
          format: double
          nullable: true
          description: Observed metric value
          example: 326.785
        unit:
          type: string
          nullable: true
          description: Measurement unit code (e.g. INDEX_1982, PCT, USD_REAL_BN)
          example: INDEX_1982
        source:
          type: string
          nullable: true
          description: Data source code (e.g. BLS, FRED, EUROSTAT)
          example: BLS
        updated_at:
          type: string
          nullable: true
          description: Timestamp when the observation was last updated
          example: '2026-03-15'
    MetricsHistoryResponse:
      type: object
      description: Full time-series history for a macroeconomic metric in a single country.
      properties:
        category:
          type: string
          nullable: true
          description: Metric category (e.g. inflation, gdp, employment)
          example: inflation
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
        from:
          type: string
          format: date
          nullable: true
          description: Earliest reference period in the returned data
          example: '2020-01-01'
        to:
          type: string
          format: date
          nullable: true
          description: Latest reference period in the returned data
          example: '2026-02-01'
        next_cursor:
          type: string
          nullable: true
          description: Cursor for the next page of results. Pass as the cursor query parameter to fetch the next page. Null when there are no more pages.
          example: '2020-01-01'
        metrics:
          type: array
          description: Metric time-series data (always a single-element array for the requested metric)
          items:
            $ref: '#/components/schemas/MetricsHistoryMetric'
    MetricsHistoryMetric:
      type: object
      description: A macroeconomic metric with its full time-series data.
      required:
        - code
        - count
        - data
      properties:
        code:
          type: string
          description: Machine-readable metric code
          example: CPI
        name:
          type: string
          nullable: true
          description: Human-readable metric name
          example: CPI All Urban Consumers
        frequency:
          type: string
          nullable: true
          description: Data release frequency (e.g. Monthly, Quarterly, Annual)
          example: Monthly
        source:
          type: string
          nullable: true
          description: Data source code (e.g. BLS, FRED, EUROSTAT)
          example: BLS
        count:
          type: integer
          description: Number of observations in the data array
          example: 74
        data:
          type: array
          description: Time-series observations ordered by reference_period ascending
          items:
            $ref: '#/components/schemas/MetricsHistoryObservation'
    MetricsHistoryObservation:
      type: object
      description: A single time-series observation for a macroeconomic metric.
      required:
        - reference_period
      properties:
        reference_period:
          type: string
          format: date
          description: Reference period for the observation (YYYY-MM-DD)
          example: '2026-02-01'
        period_end:
          type: string
          format: date
          nullable: true
          description: End date of the observation period (for quarterly/annual data)
        value:
          type: number
          format: double
          nullable: true
          description: Observed metric value
          example: 326.785
        is_revised:
          type: boolean
          description: Whether this observation has been revised from a previously published value
          example: false
    FundHolding:
      type: object
      description: Individual mutual fund holding with exposure weight.
      properties:
        name:
          type: string
          description: Holding name
        exposure:
          type: number
          description: Allocation weight (percentage)
    FundMetricItem:
      type: object
      description: A single fund metric value (latest observation for the metric name).
      required:
        - metricId
        - metricName
        - value
        - valid
      properties:
        metricId:
          type: string
          description: Machine-readable metric identifier (lowercase, e.g. nav, cumulative_return_1y)
          example: cumulative_return_1y
        metricName:
          type: string
          description: Metric name (lowercase, identical to metricId)
          example: cumulative_return_1y
        date:
          type: string
          format: date
          description: Observation date of this metric value
          example: '2026-08-31'
        value:
          type: number
          format: double
          nullable: true
          description: Metric value. Null when no value is available.
          example: 12.4
        valid:
          type: boolean
          description: Whether the metric carries a value (false when value is null)
          example: true
        unit:
          type: string
          description: Unit of measurement (MetricUnitModel value, uppercase)
          enum:
            - CURRENCY
            - PERCENTAGE
            - RATIO
            - NUMERIC
          example: PERCENTAGE
        currency:
          type: string
          nullable: true
          description: Currency code if the metric is currency-denominated (null for percentages)
          example: EUR
    IPOFinancialsSnapshot:
      type: object
      description: Headline financials for the most recent full-year period, surfaced on the hot-IPO list row.
      properties:
        period:
          type: string
          nullable: true
          description: Reporting period label (e.g. `FY2025`)
          example: FY2025
        revenue:
          type: number
          format: double
          nullable: true
          description: Total revenue for the period
          example: 18674.0
        ebitdaAdjusted:
          type: number
          format: double
          nullable: true
          description: Adjusted EBITDA for the period
          example: 6584.0
        netIncome:
          type: number
          format: double
          nullable: true
          description: Net income for the period
          example: -4940.0
        revenueYoY:
          type: number
          format: double
          nullable: true
          description: Year-over-year revenue growth (fraction, e.g. 0.3324 = 33.24%)
          example: 0.3324
    HotIPORecord:
      type: object
      description: A hot-IPO offering summary plus a headline financials snapshot.
      required:
        - symbol
      properties:
        symbol:
          type: string
          description: Planned ticker symbol
          example: SPCX
        name:
          type: string
          nullable: true
          description: Company name
          example: Space Exploration Technologies Corp.
        exchange:
          type: integer
          nullable: true
          description: Target exchange identifier for the listing
        regulator:
          type: string
          nullable: true
          description: Filing regulator (e.g. `SEC`)
          example: SEC
        filingType:
          type: string
          nullable: true
          description: Filing type (e.g. `S-1`)
          example: S-1
        status:
          type: string
          nullable: true
          description: Offering status (e.g. `Expected`, `Priced`, `Listed`)
          example: Expected
        priceType:
          type: string
          nullable: true
          description: Pricing mechanism (e.g. `fixed`, `range`)
          example: fixed
        priceLow:
          type: number
          format: double
          nullable: true
          description: Lower bound of the expected price range
          example: 135.0
        priceHigh:
          type: number
          format: double
          nullable: true
          description: Upper bound of the expected price range
          example: 135.0
        currency:
          type: string
          nullable: true
          description: Offering currency (ISO 4217)
          example: USD
        numberOfShares:
          type: integer
          nullable: true
          description: Number of shares offered
          example: 556600000
        grossProceeds:
          type: number
          format: double
          nullable: true
          description: Expected gross proceeds
          example: 75141000000.0
        impliedValuation:
          type: number
          format: double
          nullable: true
          description: Implied post-offering valuation
          example: 1750000000000.0
        confidentialFilingDate:
          type: string
          format: date
          nullable: true
          description: Confidential filing date
          example: '2026-04-01'
        publicFilingDate:
          type: string
          format: date
          nullable: true
          description: Public filing date
          example: '2026-05-20'
        expectedListingDate:
          type: string
          format: date
          nullable: true
          description: Expected listing date, resolved from the listing milestone
          example: '2026-06-12'
        financialsSnapshot:
          allOf:
            - $ref: '#/components/schemas/IPOFinancialsSnapshot'
          nullable: true
          description: Headline financials snapshot, or null when no financials exist
    IPOMilestone:
      type: object
      description: An IPO timeline stage (e.g. subscription, pricing, listing).
      properties:
        stage:
          type: string
          description: Stage key
          example: listing
        label:
          type: string
          nullable: true
          description: Human-readable stage label
          example: Day of IPO
        startsAt:
          type: string
          format: date-time
          nullable: true
          description: Stage start timestamp (ISO-8601)
        endsAt:
          type: string
          format: date-time
          nullable: true
          description: Stage end timestamp (ISO-8601)
          example: '2026-06-10T19:00:00+02:00'
        expectedDate:
          type: string
          format: date
          nullable: true
          description: Expected date for the stage
          example: '2026-06-12'
        source:
          type: string
          nullable: true
          description: Provenance of the milestone
          example: S-1
    IPOHotFinancialMetric:
      type: object
      description: 'A single financial metric for an IPO candidate.'
      properties:
        metric_name:
          type: string
          nullable: true
          description: Metric identifier (e.g. `revenue`, `totalAssets`, `capex`, `eps`)
          example: revenue
        value:
          type: number
          format: double
          nullable: true
          description: Metric value
          example: 18674000000.0
        value_type:
          type: string
          nullable: true
          description: Value semantics
          enum:
            - currency
            - ratio
            - percentage
            - numeric
          example: currency
        currency:
          type: string
          nullable: true
          description: ISO 4217 currency (null for non-currency metrics)
          example: USD
        unit:
          type: string
          nullable: true
          description: Unit of the value (e.g. `USD`, `USD/share`, `shares`)
          example: USD
        fiscal_year:
          type: integer
          nullable: true
          description: Fiscal year
          example: 2025
        fiscal_period:
          type: string
          nullable: true
          description: Fiscal period
          enum:
            - FY
            - Q1
            - Q2
            - Q3
            - Q4
            - H1
            - H2
          example: FY
        period_end_date:
          type: string
          format: date
          nullable: true
          description: Period end date
          example: '2025-12-31'
        source:
          type: string
          nullable: true
          description: Provenance of the figure
          example: SpaceX EU retail prospectus summary, Bafin-approved 2026-06-05, section B.2
        valid:
          type: boolean
          description: Whether the figure is considered valid (defaults to true)
          example: true
    IPOFinancials:
      type: object
      description: 'Statement-grouped financials for an IPO candidate. Each group is an array of

        metric objects; the three groups are always present (possibly empty).'
      properties:
        incomeStatement:
          type: array
          description: Income-statement metrics (revenue, costs, net income, EBITDA/EBIT, EPS, share counts)
          items:
            $ref: '#/components/schemas/IPOHotFinancialMetric'
        balanceSheet:
          type: array
          description: Balance-sheet metrics (cash, total assets/liabilities, equity)
          items:
            $ref: '#/components/schemas/IPOHotFinancialMetric'
        cashFlow:
          type: array
          description: Cash-flow metrics (capex, operating/investing/financing cash flow)
          items:
            $ref: '#/components/schemas/IPOHotFinancialMetric'
    IPODocument:
      type: object
      description: 'An IPO document (link/metadata). At most one document per (docType) is the

        canonical `isPrimary` language used as the i18n fallback.'
      properties:
        docType:
          type: string
          description: Document type key (e.g. `prospectus`, `sec_s1`, `prospectus_summary`)
          example: sec_s1
        label:
          type: string
          nullable: true
          description: Localized document label
          example: SEC S-1
        language:
          type: string
          nullable: true
          description: Document language (ISO 639-1 / BCP-47)
          example: en
        format:
          type: string
          nullable: true
          description: Document format
          enum:
            - pdf
            - html
          example: html
        isPrimary:
          type: boolean
          nullable: true
          description: Whether this is the canonical language for its docType (used as fallback)
          example: true
        url:
          type: string
          nullable: true
          description: Document URL, or null when not yet published
          example: https://www.sec.gov/Archives/edgar/data/1181412/000162828026036936/spaceexplorationtechnologi.htm
    IPOProfile:
      type: object
      description: Full single-IPO detail — offering plus nested milestones and statement-grouped financials. Documents are served separately by the /ipo/documents endpoint.
      required:
        - symbol
      properties:
        symbol:
          type: string
          example: SPCX
        name:
          type: string
          nullable: true
          example: Space Exploration Technologies Corp.
        exchange:
          type: integer
          nullable: true
        regulator:
          type: string
          nullable: true
          example: SEC
        filingType:
          type: string
          nullable: true
          example: S-1
        status:
          type: string
          nullable: true
          example: Expected
        priceType:
          type: string
          nullable: true
          example: fixed
        priceLow:
          type: number
          format: double
          nullable: true
          example: 135.0
        priceHigh:
          type: number
          format: double
          nullable: true
          example: 135.0
        currency:
          type: string
          nullable: true
          example: USD
        numberOfShares:
          type: integer
          nullable: true
          example: 556600000
        grossProceeds:
          type: number
          format: double
          nullable: true
          example: 75141000000.0
        impliedValuation:
          type: number
          format: double
          nullable: true
          example: 1750000000000.0
        confidentialFilingDate:
          type: string
          format: date
          nullable: true
          example: '2026-04-01'
        publicFilingDate:
          type: string
          format: date
          nullable: true
          example: '2026-05-20'
        milestones:
          type: array
          items:
            $ref: '#/components/schemas/IPOMilestone'
        financials:
          allOf:
            - $ref: '#/components/schemas/IPOFinancials'
          description: Statement-grouped financials (income statement, balance sheet, cash flow)
    NewsArticle:
      type: object
      description: Financial news article.
      properties:
        symbol:
          type: string
          nullable: true
          description: Resolved ticker the article was matched to
          example: AAPL
        title:
          type: string
          description: Article headline
          example: Apple Reports Record Q1 Revenue
        text:
          type: string
          description: Article body or summary text
        site:
          type: string
          description: Publisher domain
          example: benzinga.com
        publishedDate:
          type: string
          format: date-time
          description: Publication date and time
        url:
          type: string
          format: uri
          description: Article URL
    QuantOSAllocation:
      type: object
      description: Optimal allocation weights computed by the engine.
      properties:
        weights:
          type: object
          description: Symbol-to-weight map (e.g. AAPL = 0.4)
          additionalProperties:
            type: number
        expectedReturn:
          type: number
          format: double
          description: Annualized expected return (decimal, e.g. 0.12 = 12%)
        volatility:
          type: number
          format: double
          description: Annualized portfolio volatility (decimal)
        sharpeRatio:
          type: number
          format: double
          description: Sharpe ratio (excess return / volatility)
    QuantOSChart:
      type: object
      description: Total portfolio performance chart as a candle series.
      properties:
        t:
          type: array
          description: Unix timestamps (seconds)
          items:
            type: number
        c:
          type: array
          description: Closing values at each timestamp
          items:
            type: number
    QuantOSPrice:
      type: object
      description: Current portfolio valuation.
      properties:
        change:
          type: number
          format: double
          description: Absolute change (alias for d)
        changePercent:
          type: number
          format: double
          description: Change percentage (alias for dp)
        currentPrice:
          type: number
          format: double
          description: Current portfolio value (alias for c)
        high:
          type: number
          format: double
          description: Day high (alias for h)
        low:
          type: number
          format: double
          description: Day low (alias for l)
        open:
          type: number
          format: double
          description: Opening portfolio value (alias for o)
        previousClose:
          type: number
          format: double
          description: Previous close value (alias for pc)
        timestamp:
          type: integer
          format: int64
          description: Timestamp (Unix epoch seconds, alias for t)
        failed:
          type: array
          default: []
          description: Symbols whose quote could not be resolved; empty when all resolved
          items:
            type: string
            example: AAPL
    QuantOSRegion:
      type: object
      description: Geographic region breakdown of the portfolio.
      properties:
        regions:
          type: array
          description: List of geographic region allocations
          items:
            type: object
            properties:
              region:
                type: string
                description: Geographic region name
              weight:
                type: number
                format: double
                description: Allocation weight (decimal)
    QuantOSRequest:
      type: object
      description: Portfolio definition for Bavest QuantOS analytics.
      required:
        - portfolioItems
      properties:
        portfolioItems:
          type: array
          description: Portfolio positions with symbol, allocation weight, and purchase date
          items:
            type: object
            required:
              - symbol
              - weight
              - buyDate
            properties:
              symbol:
                type: string
                description: Ticker symbol
                example: AAPL
              weight:
                type: number
                description: Allocation weight (all weights must sum to 1.0)
                example: 0.4
              buyDate:
                type: string
                format: date
                description: Purchase date (YYYY-MM-DD).
                example: '2026-09-01'
              amount:
                type: number
                description: Number of shares held
          example:
            - symbol: AAPL
              weight: 0.4
              buyDate: '2026-09-01'
            - symbol: MSFT
              weight: 0.35
              buyDate: '2026-09-01'
            - symbol: GOOGL
              weight: 0.25
              buyDate: '2026-09-01'
        startDate:
          type: string
          format: date
          description: Analysis start date (YYYY-MM-DD)
          example: '2026-09-01'
        endDate:
          type: string
          format: date
          description: Analysis end date (YYYY-MM-DD)
          example: '2026-09-30'
        currency:
          type: string
          description: Target currency for valuation (ISO 4217)
          default: USD
          example: USD
        resolution:
          type: string
          description: Data resolution for time series
          default: D
          example: D
          enum:
            - D
            - W
            - M
    QuantOSReturn:
      type: object
      description: Portfolio return calculation.
      properties:
        totalReturn:
          type: number
          format: double
          description: Cumulative return over period (decimal)
        annualizedReturn:
          type: number
          format: double
          description: Annualized return (decimal)
        beta:
          type: number
          format: double
          description: Portfolio beta
          example: 0.0
        dividendPerShareAnnual:
          type: number
          format: double
          description: Annual dividend per share (USD)
          example: 0.0
        performanceOneWeek:
          type: number
          format: double
          description: One-week return
          example: 0.0
        performanceOneYear:
          type: number
          format: double
          description: One-year return
          example: 0.0
        performanceSixMonths:
          type: number
          format: double
          description: Six-month return
          example: 0.0
    QuantOSSector:
      type: object
      description: GICS sector breakdown of the portfolio.
      properties:
        sectors:
          type: array
          description: List of GICS sector allocations
          items:
            type: object
            properties:
              sector:
                type: string
                description: GICS sector name
              weight:
                type: number
                format: double
                description: Allocation weight (decimal)
    QuantOSStats:
      type: object
      description: Comprehensive portfolio statistics keyed by position index and total.
      additionalProperties:
        type: object
        properties:
          sharpeRatio:
            type: string
            description: Sharpe ratio for this position or total portfolio
          correlation:
            type: object
            description: Correlation matrix entries
            additionalProperties:
              oneOf:
                - type: number
                - type: string
          series:
            type: object
            description: Time series data
            properties:
              t:
                type: array
                items:
                  type: number
              c:
                type: array
                items:
                  type: number
              h:
                type: array
                items:
                  type: number
              l:
                type: array
                items:
                  type: number
              o:
                type: array
                items:
                  type: number
              s:
                type: string
              v:
                type: array
                items:
                  type: number
          stats:
            type: object
            description: Detailed performance statistics
            properties:
              riskFree:
                type: number
                format: double
              totalReturn:
                type: number
                format: double
              cagr:
                type: number
                format: double
              maxDrawdown:
                type: number
                format: double
              calmar:
                type: number
                format: double
              mtd:
                type: number
                format: double
              threeMonth:
                type: number
                format: double
              sixMonth:
                type: number
                format: double
              ytd:
                type: number
                format: double
              oneYear:
                type: number
                format: double
              threeYear:
                type: number
                format: double
                nullable: true
              fiveYear:
                type: number
                format: double
                nullable: true
              tenYear:
                type: number
                format: double
                nullable: true
              inception:
                type: number
                format: double
              dailySharpe:
                type: number
                format: double
              dailySortino:
                type: number
                format: double
              dailyMean:
                type: number
                format: double
              dailyVolume:
                type: number
                format: double
              dailySkew:
                type: number
                format: double
              dailyKurt:
                type: number
                format: double
              bestDay:
                type: number
                format: double
              worstDay:
                type: number
                format: double
              monthlySharpe:
                type: number
                format: double
              monthlySortino:
                type: number
                format: double
              monthlyMean:
                type: number
                format: double
              monthlyVol:
                type: number
                format: double
              monthlySkew:
                type: number
                format: double
              monthlyKurt:
                type: number
                format: double
              bestMonth:
                type: number
                format: double
              worstMonth:
                type: number
                format: double
              yearlySharpe:
                type: number
                format: double
              yearlySortino:
                type: number
                format: double
              yearlyMean:
                type: number
                format: double
              yearlyVol:
                type: number
                format: double
              yearlySkew:
                type: number
                format: double
                nullable: true
              yearlyKurt:
                type: number
                format: double
                nullable: true
              bestYear:
                type: number
                format: double
              worstYear:
                type: number
                format: double
              avgDrawdown:
                type: number
                format: double
              avgDrawdownDays:
                type: number
                format: double
              avgUpMonth:
                type: number
                format: double
              avgDownMonth:
                type: number
                format: double
              winYearPerc:
                type: number
                format: double
              twelveMonthWinPerc:
                type: number
                format: double
          error:
            type: string
            nullable: true
            description: Error message if computation failed for this position
    NavResponse:
      type: object
      description: Net Asset Value for an ETF or mutual fund.
      required:
        - nav
        - currency
        - date
      properties:
        nav:
          type: number
          format: double
          description: Net Asset Value per share
          example: 664.88
        currency:
          type: string
          description: NAV currency (ISO 4217)
          example: USD
        date:
          type: string
          format: date
          description: NAV observation date
          example: '2025-10-17'
    AnnualDividendSummary:
      type: object
      description: Aggregated annual dividend summary.
      properties:
        currency:
          type: string
          nullable: true
          description: ISO 4217 currency of the dividend amounts
          example: USD
        dividendFrequency:
          type: integer
          description: Annual payment frequency (1=annual, 2=semi-annual, 4=quarterly, 12=monthly)
        dividends:
          type: array
          description: List of annual dividend amounts
          items:
            type: object
            properties:
              year:
                type: integer
                description: Dividend payment year
              amount:
                type: number
                description: Total dividend amount paid in the year
    ExchangeStatus:
      type: object
      description: Exchange open/closed status.
      required:
        - exchange
        - isOpen
      properties:
        exchange:
          type: string
          description: Exchange name
        isOpen:
          type: boolean
          description: Whether the exchange is currently open for trading
        openingHour:
          type: integer
          description: Daily opening time in 24-hour format (e.g. 930 for 9:30 AM)
        closingHour:
          type: integer
          description: Daily closing time in 24-hour format (e.g. 1600 for 4:00 PM)
        timezone:
          type: string
          description: IANA timezone identifier
          example: America/New_York
    ForexQuote:
      type: object
      description: Real-time forex pair quote.
      required:
        - symbol
        - price
      properties:
        symbol:
          type: string
          description: Currency pair symbol
          example: EURUSD
        price:
          type: number
          format: double
          description: Current market price
          example: 1.15577
        change:
          type: number
          format: double
          description: Absolute price change from previous close
          example: -0.00015
        changesPercentage:
          type: number
          format: double
          description: Percentage price change from previous close
          example: -0.01297668
        dayHigh:
          type: number
          format: double
          description: Highest price during the trading day
          example: 1.15724
        dayLow:
          type: number
          format: double
          description: Lowest price during the trading day
          example: 1.15476
        open:
          type: number
          format: double
          description: Opening price for the trading day
          example: 1.1559
        previousClose:
          type: number
          format: double
          description: Previous trading day closing price
          example: 1.15592
        timestamp:
          type: string
          format: date-time
          description: Quote timestamp (ISO 8601)
          example: '2026-03-30T11:59:59'
    IPORecord:
      type: object
      description: Upcoming or recent IPO event record.
      required:
        - symbol
        - date
      properties:
        symbol:
          type: string
          description: Planned ticker symbol
        exchange:
          type: string
          nullable: true
          description: Target exchange for listing
        date:
          type: string
          format: date
          description: Expected or actual IPO date
        name:
          type: string
          description: Company name
          example: Guardian Metal Resources PLC Sponsored ADR
        numberOfShares:
          type: integer
          description: Number of shares offered in the IPO
          example: 4444400
        priceHigh:
          type: number
          format: double
          nullable: true
          description: Upper bound of the expected price range
        priceLow:
          type: number
          format: double
          nullable: true
          description: Lower bound of the expected price range
        status:
          type: string
          description: Current IPO status (e.g., Priced, Expected, Withdrawn)
          example: Priced
        totalSharesValue:
          type: number
          description: Total value of shares offered
          example: 59999400.0
    MarketCapRecord:
      type: object
      description: Historical market capitalization data point.
      required:
        - metricValue
        - metricDate
      properties:
        metricDate:
          type: string
          description: Observation date
          example: '2026-03-24T00:00:00'
        metricValue:
          type: number
          format: double
          description: Market capitalization value, in `metricCurrency`
          example: 3690170000000.0
        metricCurrency:
          type:
            - string
            - 'null'
          description: Currency of this point's `metricValue` (ISO 4217). A history can change currency from one point to the next, so read it per point.
          example: USD
    MarketCapSnapshot:
      type: object
      description: Current market capitalization.
      required:
        - metricValue
        - metricCurrency
      properties:
        metricCurrency:
          type: string
          description: Currency of the market capitalization value (ISO 4217)
          example: USD
        metricDate:
          type: string
          description: Observation date
          example: '2026-03-24T00:00:00'
        metricValue:
          type: number
          format: double
          description: Market capitalization value
          example: 3690170000000.0
    PeerCompany:
      type: object
      description: Peer company identifier.
      properties:
        symbol:
          type: string
          description: Peer company ticker symbol
          example: MSFT
        isin:
          type: string
          description: Security identifier (ISIN)
          example: US5949181045
    ScreenerFilterItem:
      type: object
      description: A single filter condition for the stock screener.
      required:
        - metric
        - operator
        - value
      properties:
        metric:
          $ref: '#/components/schemas/ScreenerMetric'
        operator:
          type: string
          enum:
            - lt
            - gt
            - gte
            - lte
            - eq
          description: 'Comparison operator. Use `eq` for exact string matches (e.g., sector, country). Numeric operators (`lt`, `gt`, `gte`, `lte`) for numeric fields.'
          example: gte
        value:
          oneOf:
            - type: number
            - type: string
            - type: boolean
          description: 'The value to compare against. Use a number for numeric metrics, a string for text fields (sector, country, industry, name, symbol) and a boolean for flags (`isReit`, with operator `eq`).'
          example: 10
    ScreenerMetric:
      type: string
      description: 'Short name for a screener metric. Choose a value from the metric enum. `debtRatio` is total liabilities / total assets; `debtToEquityRatio` is total liabilities / total equity and can be negative for negative equity. These use total liabilities, unlike `debt_to_assets` and `debt_to_equity` in financials.metrics, which use total debt; `debt_to_equity` is null for negative equity.'
      enum:
        - name
        - symbol
        - isin
        - stockExchange
        - employeeTotal
        - marketCapitalization
        - country
        - beta
        - industry
        - sector
        - price
        - isReit
        - retainedEarnings
        - totalAssets
        - currentAssets
        - fixedAssets
        - totalCurrentLiabilities
        - totalNonCurrentLiabilities
        - longTermDebt
        - totalLiabilities
        - totalEquity
        - liabilitiesAndEquity
        - operatingCashFlow
        - investingCashFlow
        - financingCashFlow
        - capitalExpenditure
        - freeCashFlow
        - netIncomeAfterTaxes
        - totalRevenue
        - grossIncome
        - ebit
        - pretaxIncome
        - ebitda
        - eps
        - stockPrice
        - shareOutstanding
        - c
        - dp
        - environmentScore
        - governanceScore
        - socialScore
        - totalESGScore
        - dividendPerShare
        - dividendPerShareAnnual
        - 5DayPriceReturnDaily
        - 13WeekPriceReturnDaily
        - 26WeekPriceReturnDaily
        - 52WeekPriceReturnDaily
        - roaRfy
        - bookValuePerShareAnnual
        - cashFlowPerShareAnnual
        - dividendYield5Y
        - dividendGrowthRate5Y
        - epsGrowth3Y
        - epsGrowth5Y
        - capitalSpendingGrowth5Y
        - currentEv/freeCashFlowAnnual
        - currentEv/freeCashFlowTTM
        - revenueEmployeeAnnual
        - revenueEmployeeTTM
        - revenueGrowth3Y
        - revenuePerShareAnnual
        - revenuePerShareTTM
        - revenueShareGrowth5Y
        - payoutRatioAnnual
        - payoutRatioTTM
        - performance
        - priceEarningsRatio
        - priceBookRatio
        - priceCashflowRatio
        - priceSalesRatio
        - ev/ebitda
        - ev/ebit
        - ev/fcf
        - ev
        - ev/revenue
        - propertyPlantEquipment
        - ev/sales
        - equityRatio
        - debtRatio
        - debtToEquityRatio
        - dynamicLeverage
        - cataRatio
        - currentRatio
        - fixedAssetIntensity
        - ppeRatio
        - assetCoverage1
        - assetCoverage2
        - cashRatio
        - quickRatio
        - returnOnEquity
        - salesReturn
        - ebitMargin
        - ebitdaMargin
        - capitalTurnover
        - assetsReturn
        - fundamentalScore
        - totalScore
        - sentimentScore
      example: returnOnEquity
    ScreenerResult:
      type: object
      description: 'A single screener hit. Always contains `symbol`, `name`, and `isin`. Additional keys are the response field names for each queried metric (e.g., `fundamentals.revenue.equityReturn` for the `returnOnEquity` filter). Values are `null` when the metric is unavailable for the security.'
      required:
        - symbol
        - name
        - isin
      properties:
        symbol:
          type: string
          description: Ticker symbol.
          example: AAPL
        name:
          type: string
          description: Company name.
          example: Apple Inc
        isin:
          type: string
          description: ISIN identifier.
          example: US0378331005
      additionalProperties:
        nullable: true
        oneOf:
          - type: number
          - type: string
        description: 'Queried metric value keyed by its response field name. Returns `null` when the metric is unavailable for the security.'
        example: 157.41
    ScreenerSortItem:
      type: object
      description: A single sort criterion for screener results.
      required:
        - metric
        - order
      properties:
        metric:
          $ref: '#/components/schemas/ScreenerMetric'
        order:
          type: string
          enum:
            - asc
            - desc
          description: Sort direction.
          example: desc
    SearchResult:
      type: object
      description: 'Security search result matching the query.


        `companyName` and `isActivelyTrading` are returned by `/v2/reference/search`

        only; the listings under `/v2/reference/search/aggregated` carry the

        identity fields and the company name sits on the enclosing group.'
      required:
        - symbol
        - type
      properties:
        symbol:
          type: string
          description: Ticker symbol
          example: AAPL
        type:
          type: string
          description: 'Asset class of the security (e.g. EQUITY, ETF, ETP, MUTUAL_FUND,

            CLOSED_END_FUND, BOND, ADR, INDEX, CRYPTO_CURRENCY, CURRENCY,

            COMMODITY, CERTIFICATE).


            `EQUITY` und `STOCK` sind im Bestand beide vergeben und meinen

            dasselbe; die Suche vereinheitlicht sie zu `EQUITY` und stellt das

            urspruengliche `STOCK` in `subtype`.'
          example: EQUITY
        subtype:
          type:
            - string
            - 'null'
          description: 'Feinere Klassifizierung, sofern vorhanden. Traegt unter anderem das

            urspruengliche `STOCK`, wenn `type` zu `EQUITY` vereinheitlicht wurde.

            `null`, wenn keine feinere Angabe vorliegt.'
          example: STOCK
        exchange:
          type:
            - string
            - 'null'
          description: 'Primary listing exchange. `null`, wenn zu dem Papier keine Boerse

            gefuehrt wird, etwa bei OTC-Anleihen ohne Handelsplatz.'
          example: NASDAQ
        isin:
          type:
            - string
            - 'null'
          description: ISIN code (if available)
          example: US0378331005
        companyName:
          type: string
          description: Full company name
          example: Leverage Shares 3x Apple ETC
        isActivelyTrading:
          type:
            - boolean
            - 'null'
          description: 'Whether the security is actively trading. `null`, wenn die Quelle dazu

            nichts sagt; das betrifft vor allem Publikumsfonds, fuer die kein

            Handelsstatus gefuehrt wird (z. B. LU0327386487).'
          example: true
        isAdr:
          type: boolean
          description: Whether the security is an American Depositary Receipt
          example: false
        isEtf:
          type: boolean
          description: Whether the security is an ETF
          example: true
        isFund:
          type: boolean
          description: Whether the security is a fund
          example: false
        isReit:
          type:
            - boolean
            - 'null'
          description: 'Whether the company is a REIT (real estate investment trust): its

            industry starts with "REIT", e.g. Realty Income "REIT - Retail".

            Never true for ETFs or funds. `null` when no industry is known.'
          example: false
    SectorPerformance:
      type: object
      description: Market sector performance snapshot.
      required:
        - sector
        - changesPercentage
      properties:
        sector:
          type: string
          description: Market sector name
        changesPercentage:
          type: number
          format: double
          description: Sector performance change (%, intraday)
