openapi: 3.1.0
info:
  title: AIsa API
  description: >-
    Unified API for AI models, social data, financial data, prediction markets, search, and media generation. All
    endpoints require a Bearer token via the Authorization header.
  version: 1.4.0
  contact:
    name: AIsa
    url: https://aisa.one
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-changelog:
    - version: 1.4.0
      date: '2026-04-22'
      summary: CoinGecko crypto data skill, llms.txt root discovery, and Atom changelog feed
      changes:
        - type: added
          description: >-
            Crypto Market Data skill with 21 CoinGecko endpoints — prices, coin data, charts, OHLC, tickers, categories,
            exchanges, trending, and news
        - type: added
          description: llms.txt served at site root (/llms.txt) for LLM auto-discovery per the llms.txt spec
        - type: added
          description: Build-time llms.txt sync script (generate:llms-txt) fetching from aisa.one/docs source of truth
        - type: added
          description: Atom 1.0 changelog feed at /apis/changelog.xml for programmatic subscription
        - type: added
          description: Versioned x-changelog embedded in agent-card.json and ai-plugin.json discovery files
        - type: added
          description: >-
            Shared changelog parser utility (scripts/lib/parseChangelog.mjs) eliminating duplication across 3 generation
            scripts
        - type: added
          description: Llms-txt directive in robots.txt for LLM crawler discoverability
        - type: changed
          description: CoinGecko endpoint pricing updated to $0.008 per call across all 21 endpoints
    - version: 1.3.0
      date: '2026-04-22'
      summary: OpenAPI spec synced from GitHub source of truth with versioned changelog
      changes:
        - type: changed
          description: OpenAPI spec now auto-generated from AIsa-team/docs GitHub repo as source of truth
        - type: added
          description: Versioned changelog system (x-changelog) embedded in OpenAPI spec
        - type: added
          description: API changelog page at /apis/changelog for consumers to track changes
        - type: added
          description: CI drift detection workflow for generated files (.github/workflows/check-generated.yml)
        - type: added
          description: Auto-generated ai-plugin.json from skills.ts for ChatGPT-era plugin compatibility
        - type: added
          description: Offline mode (--offline flag) for OpenAPI generation using cached specs
    - version: 1.2.0
      date: '2026-04-21'
      summary: Fleshed out OpenAPI stubs and added method badges to skill endpoints
      changes:
        - type: added
          description: Polymarket candlesticks path-parameter variant endpoint
          endpoints:
            - /apis/v1/polymarket/candlesticks/{condition_id}
        - type: added
          description: Polymarket wallet PnL path-parameter variant endpoint
          endpoints:
            - /apis/v1/polymarket/wallet/pnl/{wallet_address}
        - type: added
          description: Scholar explain GET variant endpoint
          endpoints:
            - /apis/v1/scholar/explain
        - type: added
          description: Scholar smart search GET variant endpoint
          endpoints:
            - /apis/v1/scholar/search/smart
        - type: added
          description: Video generation task polling query-parameter variant
          endpoints:
            - /apis/v1/services/aigc/tasks
        - type: added
          description: HTTP method badges (GET/POST) on all skill detail page endpoints
        - type: fixed
          description: Fixed 6 double-prefixed /apis/v1/ tool paths in skills data
    - version: 1.1.0
      date: '2026-04-20'
      summary: Auto-generated agent-card.json and ai-plugin.json from skills data
      changes:
        - type: added
          description: agent-card.json auto-generated from skills.ts at build time
        - type: added
          description: ai-plugin.json auto-generated from skills.ts at build time
        - type: added
          description: Sitemap entries for all model aliases with canonical redirects
        - type: added
          description: Alias staleness detection tests to catch broken redirects
        - type: added
          description: 25+ model alias redirects for deprecated/renamed models
    - version: 1.0.0
      date: '2026-04-15'
      summary: Initial OpenAPI specification with 111 endpoints across 10 categories
      changes:
        - type: added
          description: 50+ AI model endpoints via OpenAI-compatible, Anthropic, and Google interfaces
          endpoints:
            - /v1/chat/completions
            - /v1/messages
        - type: added
          description: Twitter/X endpoints — search, profiles, tweets, communities, trends, and engagement
        - type: added
          description: Financial data endpoints — stock prices, SEC filings, analyst estimates, macro data
          endpoints:
            - /apis/v1/tavily/search
        - type: added
          description: Prediction market endpoints — Polymarket, Kalshi, and matching markets
          endpoints:
            - /apis/v1/tavily/search
        - type: added
          description: Web and news search via Tavily
          endpoints:
            - /apis/v1/tavily/search
        - type: added
          description: YouTube search and video metadata
          endpoints:
            - /apis/v1/youtube/search
        - type: added
          description: Scholar search — academic papers, explanations, and smart search
        - type: added
          description: CoinGecko crypto data — prices, markets, exchanges, trending
        - type: added
          description: Image generation and editing endpoints
        - type: added
          description: Video generation (Wan family) with task polling
servers:
  - url: https://api.aisa.one
    description: AIsa production API gateway
security:
  - bearerAuth: []
tags:
  - name: AI Models
    description: OpenAI-compatible, Anthropic, and Google model inference endpoints
  - name: Twitter / X
    description: Twitter/X social data — search, profiles, tweets, communities, trends, and engagement actions
  - name: Financial Data
    description: Stock prices, SEC filings, earnings, analyst estimates, and macro indicators
  - name: Prediction Markets
    description: Polymarket, Kalshi, and matching markets — events, orderbooks, and positions
  - name: Crypto Data
    description: CoinGecko cryptocurrency data — prices, markets, exchanges, and trending
  - name: Web & News Search
    description: Tavily web and news search, crawling, and content extraction
  - name: Perplexity Search
    description: Perplexity-powered AI search with citations
  - name: Scholar Search
    description: Academic paper search, explanations, and smart search via txyz
  - name: YouTube Search
    description: YouTube video search and metadata
  - name: Image Generation
    description: AI image generation and editing via DALL-E and other models
  - name: Video Generation
    description: AI video generation (Wan family) with async task polling
paths:
  /apis/v1/analyst-estimates:
    get:
      summary: Analyst Estimates
      description: ''
      operationId: getAnalystEstimates
      parameters:
        - name: ticker
          in: query
          description: The ticker to get analyst estimates for.
          required: true
          schema:
            type: string
        - name: period
          in: query
          description: >-
            The period to get analyst estimates for. Use the /analyst-estimates/periods endpoint to get a list of
            available periods. Defaults to 'annual'.
          required: false
          schema:
            type: string
            enum:
              - annual
              - quarterly
        - name: limit
          in: query
          description: The maximum number of estimates to return (max 3 for annual, 12 for quarterly).
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Analyst estimates response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalystEstimatesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      tags:
        - Financial Data
  /apis/v1/coingecko/categories:
    get:
      summary: Category leaderboard with market cap, volume, and top coins
      description: Auto-generated stub from Crypto Market Data skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getCoingeckoCategories
      tags:
        - Crypto Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/coingecko/categories/list:
    get:
      summary: All category IDs and names
      description: Auto-generated stub from Crypto Market Data skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getCoingeckoCategoriesList
      tags:
        - Crypto Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/coingecko/coins/categories:
    get:
      summary: Categories with Market Data
      description: All categories with market cap, volume, and top-3 coins.
      operationId: coingeckoCategoriesMarketData
      parameters:
        - name: order
          in: query
          schema:
            type: string
            enum:
              - market_cap_desc
              - market_cap_asc
              - name_desc
              - name_asc
              - market_cap_change_24h_desc
              - market_cap_change_24h_asc
      responses:
        '200':
          description: Array of categories with market data.
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/categories/list:
    get:
      summary: Categories List
      description: List all categories used by CoinGecko.
      operationId: coingeckoCategoriesList
      responses:
        '200':
          description: Array of categories.
          content:
            application/json:
              example:
                - category_id: layer-1
                  name: Layer 1 (L1)
                - category_id: meme-token
                  name: Meme
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/list:
    get:
      summary: Coins List (ID Map)
      description: List all coins with id, symbol, and name. Use to map symbols to CoinGecko IDs.
      operationId: coingeckoCoinsList
      parameters:
        - name: include_platform
          in: query
          description: Include platform + contract addresses.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Array of coins.
          content:
            application/json:
              example:
                - id: bitcoin
                  symbol: btc
                  name: Bitcoin
                - id: ethereum
                  symbol: eth
                  name: Ethereum
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/markets:
    get:
      summary: Coins Markets
      description: 'List all coins with market data: price, market cap, volume, and other metrics.'
      operationId: coingeckoCoinsMarkets
      parameters:
        - $ref: '#/components/parameters/VsCurrency'
        - name: ids
          in: query
          description: Comma-separated CoinGecko coin IDs.
          schema:
            type: string
          example: bitcoin,ethereum
        - name: category
          in: query
          description: Filter by category (see `/coins/categories/list`).
          schema:
            type: string
        - name: order
          in: query
          schema:
            type: string
            enum:
              - market_cap_desc
              - market_cap_asc
              - volume_desc
              - volume_asc
              - id_asc
              - id_desc
            default: market_cap_desc
        - name: per_page
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 250
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: sparkline
          in: query
          schema:
            type: boolean
            default: false
        - name: price_change_percentage
          in: query
          description: 'Comma-separated windows: `1h,24h,7d,14d,30d,200d,1y`.'
          schema:
            type: string
      responses:
        '200':
          description: Array of coin market entries.
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{id}:
    get:
      summary: Coin Data by ID
      description: Current data (price, markets, links, community, developer data) for a coin.
      operationId: coingeckoCoinById
      parameters:
        - $ref: '#/components/parameters/CoinId'
        - name: localization
          in: query
          schema:
            type: boolean
            default: true
        - name: tickers
          in: query
          schema:
            type: boolean
            default: true
        - name: market_data
          in: query
          schema:
            type: boolean
            default: true
        - name: community_data
          in: query
          schema:
            type: boolean
            default: true
        - name: developer_data
          in: query
          schema:
            type: boolean
            default: true
        - name: sparkline
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Coin object.
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{id}/contract/{address}:
    get:
      summary: Coin Data by Token Address
      description: Coin data for a token by contract address on a supported platform.
      operationId: coingeckoCoinByTokenAddress
      parameters:
        - name: id
          in: path
          required: true
          description: Platform ID (e.g., `ethereum`).
          schema:
            type: string
          example: ethereum
        - name: address
          in: path
          required: true
          description: ERC-20 / BEP-20 contract address.
          schema:
            type: string
      responses:
        '200':
          description: Coin object.
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{id}/contract/{address}/market_chart:
    get:
      summary: Coin Historical Chart by Contract
      description: Historical market data for a token by contract address.
      operationId: coingeckoCoinMarketChartByContract
      parameters:
        - name: id
          in: path
          required: true
          description: Platform ID.
          schema:
            type: string
          example: ethereum
        - name: address
          in: path
          required: true
          description: Contract address.
          schema:
            type: string
        - $ref: '#/components/parameters/VsCurrency'
        - $ref: '#/components/parameters/Days'
      responses:
        '200':
          description: Same shape as `/coins/{id}/market_chart`.
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{id}/history:
    get:
      summary: Coin Historical Data
      description: Historical snapshot (price, market cap, volume) for a coin on a given date.
      operationId: coingeckoCoinHistory
      parameters:
        - $ref: '#/components/parameters/CoinId'
        - name: date
          in: query
          required: true
          description: Date in `dd-mm-yyyy` format.
          schema:
            type: string
          example: 30-12-2024
        - name: localization
          in: query
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Snapshot object for the given date.
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{id}/market_chart:
    get:
      summary: Coin Historical Chart
      description: Historical market data (price, market cap, 24h volume) for a coin.
      operationId: coingeckoCoinMarketChart
      parameters:
        - $ref: '#/components/parameters/CoinId'
        - $ref: '#/components/parameters/VsCurrency'
        - $ref: '#/components/parameters/Days'
        - name: interval
          in: query
          description: '`daily` (default when days ≥ 90), else auto-granular.'
          schema:
            type: string
            enum:
              - daily
      responses:
        '200':
          description: Three time-series arrays.
          content:
            application/json:
              example:
                prices:
                  - - 1713398400000
                    - 67234.12
                  - - 1713402000000
                    - 67301.55
                market_caps:
                  - - 1713398400000
                    - 1321498765432
                total_volumes:
                  - - 1713398400000
                    - 25679876543
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{id}/market_chart/range:
    get:
      summary: Coin Market Chart Range
      description: Historical market data within an explicit UNIX timestamp range.
      operationId: coingeckoCoinMarketChartRange
      parameters:
        - $ref: '#/components/parameters/CoinId'
        - $ref: '#/components/parameters/VsCurrency'
        - name: from
          in: query
          required: true
          description: Start UNIX timestamp (seconds).
          schema:
            type: integer
          example: 1713398400
        - name: to
          in: query
          required: true
          description: End UNIX timestamp (seconds).
          schema:
            type: integer
          example: 1713484800
      responses:
        '200':
          description: Same shape as `/coins/{id}/market_chart`.
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{id}/ohlc:
    get:
      summary: Coin OHLC
      description: OHLC candles for a coin.
      operationId: coingeckoCoinOhlc
      parameters:
        - $ref: '#/components/parameters/CoinId'
        - $ref: '#/components/parameters/VsCurrency'
        - name: days
          in: query
          required: true
          description: '`1`, `7`, `14`, `30`, `90`, `180`, `365`.'
          schema:
            type: string
          example: '7'
      responses:
        '200':
          description: 'Array of OHLC rows: `[timestamp, open, high, low, close]`.'
          content:
            application/json:
              example:
                - - 1713398400000
                  - 67000
                  - 67500
                  - 66900
                  - 67234.12
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{id}/tickers:
    get:
      summary: Coin Tickers
      description: Tickers (exchange-listed pairs) for a coin.
      operationId: coingeckoCoinTickers
      parameters:
        - $ref: '#/components/parameters/CoinId'
        - name: exchange_ids
          in: query
          description: Comma-separated exchange IDs.
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: order
          in: query
          schema:
            type: string
            enum:
              - trust_score_desc
              - trust_score_asc
              - volume_desc
        - name: depth
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Tickers array.
      tags:
        - Crypto Data
  /apis/v1/coingecko/coins/{platform}/contract/{address}:
    get:
      summary: Full coin data by contract address
      description: Auto-generated stub from Crypto Market Data skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getCoingeckoCoinsPlatformContractAddress
      tags:
        - Crypto Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/coingecko/coins/{platform}/contract/{address}/market_chart:
    get:
      summary: Market chart by contract address
      description: Auto-generated stub from Crypto Market Data skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getCoingeckoCoinsPlatformContractAddressMarketChart
      tags:
        - Crypto Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/coingecko/exchanges:
    get:
      summary: Exchanges List
      description: List all exchanges with current trading volume and metadata.
      operationId: coingeckoExchangesList
      parameters:
        - name: per_page
          in: query
          schema:
            type: integer
            default: 100
            maximum: 250
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Array of exchange objects.
      tags:
        - Crypto Data
  /apis/v1/coingecko/exchanges/list:
    get:
      summary: Exchanges List (ID Map)
      description: List all exchange IDs and names — use to resolve exchange names to IDs.
      operationId: coingeckoExchangesListIdMap
      responses:
        '200':
          description: Array of `{id, name}`.
          content:
            application/json:
              example:
                - id: binance
                  name: Binance
                - id: gdax
                  name: Coinbase Exchange
      tags:
        - Crypto Data
  /apis/v1/coingecko/exchanges/{id}:
    get:
      summary: Exchange Data by ID
      description: Detailed data for a single exchange (volume, tickers, trust score, etc.).
      operationId: coingeckoExchangeById
      parameters:
        - $ref: '#/components/parameters/ExchangeId'
      responses:
        '200':
          description: Exchange object.
      tags:
        - Crypto Data
  /apis/v1/coingecko/exchanges/{id}/tickers:
    get:
      summary: Exchange Tickers
      description: Tickers traded on a given exchange.
      operationId: coingeckoExchangeTickers
      parameters:
        - $ref: '#/components/parameters/ExchangeId'
        - name: coin_ids
          in: query
          description: Filter by coin IDs (comma-separated).
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: depth
          in: query
          schema:
            type: boolean
            default: false
        - name: order
          in: query
          schema:
            type: string
            enum:
              - trust_score_desc
              - volume_desc
      responses:
        '200':
          description: Tickers array.
      tags:
        - Crypto Data
  /apis/v1/coingecko/news:
    get:
      summary: Crypto News
      description: Latest crypto news articles aggregated by CoinGecko.
      operationId: coingeckoNews
      responses:
        '200':
          description: Array of news articles.
          content:
            application/json:
              example:
                data:
                  - title: Bitcoin hits new high
                    url: https://example.com/article
                    published_at: 1713398400
      tags:
        - Crypto Data
  /apis/v1/coingecko/search/trending:
    get:
      summary: Trending Search
      description: Top-7 trending coin searches on CoinGecko in the last 24 hours.
      operationId: coingeckoTrendingSearch
      responses:
        '200':
          description: Trending coins, nfts, and categories.
          content:
            application/json:
              example:
                coins:
                  - item:
                      id: bitcoin
                      name: Bitcoin
                      symbol: BTC
                      market_cap_rank: 1
      tags:
        - Crypto Data
  /apis/v1/coingecko/simple/price:
    get:
      summary: Simple Price
      description: Current price for any cryptocurrencies in any supported currencies.
      operationId: coingeckoSimplePrice
      parameters:
        - name: ids
          in: query
          required: true
          description: Comma-separated coin IDs.
          schema:
            type: string
          example: bitcoin,ethereum
        - name: vs_currencies
          in: query
          required: true
          description: Comma-separated target currencies.
          schema:
            type: string
          example: usd,eur
        - name: include_market_cap
          in: query
          schema:
            type: boolean
            default: false
        - name: include_24hr_vol
          in: query
          schema:
            type: boolean
            default: false
        - name: include_24hr_change
          in: query
          schema:
            type: boolean
            default: false
        - name: include_last_updated_at
          in: query
          schema:
            type: boolean
            default: false
        - name: precision
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Map keyed by coin id.
          content:
            application/json:
              example:
                bitcoin:
                  usd: 67234.12
                  eur: 62019.45
                ethereum:
                  usd: 3412
                  eur: 3147.8
      tags:
        - Crypto Data
  /apis/v1/coingecko/simple/supported_vs_currencies:
    get:
      summary: Supported Currencies
      description: List of all supported fiat and crypto currencies for `vs_currency` parameters.
      operationId: coingeckoSupportedVsCurrencies
      responses:
        '200':
          description: Array of currency codes.
          content:
            application/json:
              example:
                - btc
                - eth
                - usd
                - eur
                - jpy
                - gbp
      tags:
        - Crypto Data
  /apis/v1/coingecko/simple/token_price/{id}:
    get:
      summary: Coin Price by Token Address
      description: Current price of one or more tokens by contract address on a supported platform.
      operationId: coingeckoTokenPriceByAddress
      parameters:
        - name: id
          in: path
          required: true
          description: Platform ID (e.g., `ethereum`, `binance-smart-chain`, `polygon-pos`).
          schema:
            type: string
          example: ethereum
        - name: contract_addresses
          in: query
          required: true
          description: Comma-separated contract addresses.
          schema:
            type: string
          example: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
        - name: vs_currencies
          in: query
          required: true
          description: Comma-separated target currencies.
          schema:
            type: string
          example: usd
        - name: include_market_cap
          in: query
          schema:
            type: boolean
        - name: include_24hr_vol
          in: query
          schema:
            type: boolean
        - name: include_24hr_change
          in: query
          schema:
            type: boolean
        - name: include_last_updated_at
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Map keyed by contract address.
      tags:
        - Crypto Data
  /apis/v1/coingecko/simple/token_price/{platform}:
    get:
      summary: Price by on-chain contract address
      description: Auto-generated stub from Crypto Market Data skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getCoingeckoSimpleTokenPricePlatform
      tags:
        - Crypto Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/company/facts:
    get:
      tags:
        - Company Information
      operationId: getCompanyFacts
      summary: Get company facts
      description: Get company facts for a ticker.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol.
          required: false
          schema:
            type: string
        - name: cik
          in: query
          description: The CIK of the company.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Company facts response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyFactsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/earnings:
    get:
      tags:
        - Earnings
      operationId: getEarnings
      summary: Get earnings snapshot
      description: >-
        Get the most recent earnings snapshot for a ticker. Optional estimate/surprise and change fields are returned
        only when available.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Earnings response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarningsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/earnings/press-releases:
    get:
      tags:
        - Earnings
      operationId: getEarningsPressReleases
      summary: Get earnings press releases
      description: Get earnings press releases for a ticker.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Earnings press releases response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PressReleasesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/filings:
    get:
      tags:
        - SEC Filings
      operationId: getFilings
      summary: Get SEC filings
      description: Get SEC filings for a company.
      parameters:
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company.
          required: false
          schema:
            type: string
        - name: ticker
          in: query
          description: The ticker symbol.
          required: false
          schema:
            type: string
        - name: filing_type
          in: query
          description: >-
            Filter by one or more filing types. Repeat the query parameter to pass multiple values (e.g.
            filing_type=10-Q&filing_type=10-K).
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - 10-K
                - 10-Q
                - 8-K
                - 20-F
                - 6-K
          style: form
          explode: true
        - name: limit
          in: query
          description: 'The maximum number of filings to return (default: 10).'
          required: false
          schema:
            type: integer
            minimum: 1
            default: 10
      responses:
        '200':
          description: SEC filings response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilingsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/filings/items:
    get:
      tags:
        - SEC Filings
      operationId: getFilingItems
      summary: Get SEC filing items
      description: Get the raw text Items from an SEC filing.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol.
          required: true
          schema:
            type: string
        - name: filing_type
          in: query
          description: The type of filing.
          required: true
          schema:
            type: string
            enum:
              - 10-K
              - 10-Q
              - 8-K
        - name: year
          in: query
          description: The year of the filing.
          required: true
          schema:
            type: integer
        - name: quarter
          in: query
          description: The quarter of the filing if 10-Q.
          required: false
          schema:
            type: integer
        - name: item
          in: query
          description: The item to get.
          required: false
          schema:
            type: string
            enum:
              - Item-1
              - Item-1A
              - Item-1B
              - Item-2
              - Item-3
              - Item-4
              - Item-5
              - Item-6
              - Item-7
              - Item-7A
              - Item-8
              - Item-9
              - Item-9A
              - Item-9B
              - Item-10
              - Item-11
              - Item-12
              - Item-13
              - Item-14
              - Item-15
              - Item-16
              - Item-1.01
              - Item-1.02
              - Item-1.03
              - Item-1.04
              - Item-2.01
              - Item-2.02
              - Item-2.03
              - Item-2.04
              - Item-2.05
              - Item-2.06
              - Item-3.01
              - Item-3.02
              - Item-3.03
              - Item-4.01
              - Item-4.02
              - Item-5.01
              - Item-5.02
              - Item-5.03
              - Item-5.04
              - Item-5.05
              - Item-5.06
              - Item-5.07
              - Item-5.08
              - Item-6.01
              - Item-6.02
              - Item-6.03
              - Item-6.04
              - Item-6.05
              - Item-7.01
              - Item-8.01
              - Item-9.01
        - name: accession_number
          in: query
          description: The accession number of the filing if 8-K.
          required: false
          schema:
            type: string
        - name: include_exhibits
          in: query
          description: >-
            Whether to include the raw text from linked exhibits. Only applicable for 8-K filings. When true, exhibit
            objects will include the 'text' field containing the full exhibit content.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: SEC filing items response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilingItemsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/financial-metrics:
    get:
      tags:
        - Financial Metrics
      operationId: getFinancialMetrics
      summary: Get financial metrics
      description: >-
        Get financial metrics for a ticker, including valuation, profitability, efficiency, liquidity, leverage, growth,
        and per share metrics.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol of the company. Required if cik is not provided.
          required: false
          schema:
            type: string
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company. Can be used instead of ticker.
          required: false
          schema:
            type: string
        - name: period
          in: query
          description: The time period for the financial data.
          required: true
          schema:
            type: string
            enum:
              - annual
              - quarterly
              - ttm
        - name: limit
          in: query
          description: The maximum number of results to return.
          required: false
          schema:
            type: integer
        - $ref: '#/components/parameters/ReportPeriod'
        - $ref: '#/components/parameters/ReportPeriodGte'
        - $ref: '#/components/parameters/ReportPeriodLte'
        - $ref: '#/components/parameters/ReportPeriodGt'
        - $ref: '#/components/parameters/ReportPeriodLt'
      responses:
        '200':
          description: The historical financial metrics and ratios for a ticker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialMetricsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/financial-metrics/snapshot:
    get:
      tags:
        - Financial Metrics
      operationId: getFinancialMetricsSnapshot
      summary: Financial Metrics Snapshot (Real-Time)
      description: >-
        Get the real-time financial metrics snapshot for a stock, including valuation ratios, profitability, efficiency,
        liquidity, leverage, growth, and per share metrics.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol of the company.
          required: false
          schema:
            type: string
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company. Can be used instead of ticker.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Financial metrics snapshot response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialMetricSnapshotResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/financial/analyst-estimates:
    get:
      summary: EPS estimates
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialAnalystEstimates
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/company/facts:
    get:
      summary: Company facts (by ticker or CIK)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialCompanyFacts
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/earnings/press-releases:
    get:
      summary: Earnings press releases (~2,776 supported tickers)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialEarningsPressReleases
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/filings:
    get:
      summary: SEC filings
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFilings
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/filings/items:
    get:
      summary: SEC filing items (requires filing_type and year)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFilingsItems
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financial-metrics:
    get:
      summary: Historical metrics (requires period)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFinancialMetrics
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financial-metrics/snapshot:
    get:
      summary: Real-time financial metrics
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFinancialMetricsSnapshot
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financials:
    get:
      summary: All financial statements (requires period)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFinancials
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financials/balance-sheets:
    get:
      summary: Balance sheets (requires period)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFinancialsBalanceSheets
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financials/cash-flow-statements:
    get:
      summary: Cash flow statements (requires period)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFinancialsCashFlowStatements
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financials/income-statements:
    get:
      summary: Income statements (requires period)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFinancialsIncomeStatements
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financials/search/line-items:
    post:
      summary: Search specific line items across tickers
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: postFinancialFinancialsSearchLineItems
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financials/search/screener:
    post:
      summary: Stock screener
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: postFinancialFinancialsSearchScreener
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/financials/segmented-revenues:
    get:
      summary: Revenue by segment and geography (requires period)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialFinancialsSegmentedRevenues
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/insider-trades:
    get:
      summary: Insider trades
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialInsiderTrades
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/institutional-ownership:
    get:
      summary: Institutional ownership (by ticker or investor)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialInstitutionalOwnership
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/macro/interest-rates:
    get:
      summary: Historical rates
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialMacroInterestRates
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/macro/interest-rates/snapshot:
    get:
      summary: Current interest rates
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialMacroInterestRatesSnapshot
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/news:
    get:
      summary: Company news by ticker
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialNews
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financial/prices:
    get:
      summary: Historical stock prices (requires interval params)
      description: Auto-generated stub from MarketPulse skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getFinancialPrices
      tags:
        - Financial Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/financials:
    get:
      tags:
        - Financial Statements
      operationId: getAllFinancialStatements
      summary: Get all financial statements
      description: Get all financial statements for a ticker.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol. Required if cik is not provided.
          required: false
          schema:
            type: string
        - name: period
          in: query
          description: The time period of the financial statements.
          required: true
          schema:
            type: string
            enum:
              - annual
              - quarterly
              - ttm
        - name: limit
          in: query
          description: The maximum number of financial statements to return.
          schema:
            type: integer
            format: int32
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/ReportPeriod'
        - $ref: '#/components/parameters/ReportPeriodGte'
        - $ref: '#/components/parameters/ReportPeriodLte'
        - $ref: '#/components/parameters/ReportPeriodGt'
        - $ref: '#/components/parameters/ReportPeriodLt'
      responses:
        '200':
          description: Financial statements response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/financials/balance-sheets:
    get:
      tags:
        - Financial Statements
      operationId: getBalanceSheets
      summary: Get balance sheets
      description: Get balance sheets for a ticker.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol. Required if cik is not provided.
          required: false
          schema:
            type: string
        - name: period
          in: query
          description: The time period of the balance sheets.
          required: true
          schema:
            type: string
            enum:
              - annual
              - quarterly
              - ttm
        - name: limit
          in: query
          description: The maximum number of balance sheets to return
          schema:
            type: integer
            format: int32
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/ReportPeriod'
        - $ref: '#/components/parameters/ReportPeriodGte'
        - $ref: '#/components/parameters/ReportPeriodLte'
        - $ref: '#/components/parameters/ReportPeriodGt'
        - $ref: '#/components/parameters/ReportPeriodLt'
      responses:
        '200':
          description: Balance sheets response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceSheetResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/financials/cash-flow-statements:
    get:
      tags:
        - Financial Statements
      operationId: getCashFlowStatements
      summary: Get cash flow statements
      description: Get cash flow statements for a ticker.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol. Required if cik is not provided.
          required: false
          schema:
            type: string
        - name: period
          in: query
          description: The time period of the cash flow statements.
          required: true
          schema:
            type: string
            enum:
              - annual
              - quarterly
              - ttm
        - name: limit
          in: query
          description: The maximum number of cash flow statements to return.
          schema:
            type: integer
            format: int32
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/ReportPeriod'
        - $ref: '#/components/parameters/ReportPeriodGte'
        - $ref: '#/components/parameters/ReportPeriodLte'
        - $ref: '#/components/parameters/ReportPeriodGt'
        - $ref: '#/components/parameters/ReportPeriodLt'
      responses:
        '200':
          description: Cash flow statements response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashFlowStatementResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/financials/income-statements:
    get:
      tags:
        - Financial Statements
      operationId: getIncomeStatements
      summary: Get income statements
      description: Get income statements for a ticker.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol. Required if cik is not provided.
          required: false
          schema:
            type: string
        - name: period
          in: query
          description: The time period of the income statements.
          required: true
          schema:
            type: string
            enum:
              - annual
              - quarterly
              - ttm
        - name: limit
          in: query
          description: The maximum number of income statements to return.
          schema:
            type: integer
            format: int32
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/ReportPeriod'
        - $ref: '#/components/parameters/ReportPeriodGte'
        - $ref: '#/components/parameters/ReportPeriodLte'
        - $ref: '#/components/parameters/ReportPeriodGt'
        - $ref: '#/components/parameters/ReportPeriodLt'
      responses:
        '200':
          description: Income statements response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomeStatementResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/financials/search/line-items:
    post:
      tags:
        - Financial Statements
      operationId: searchLineItems
      summary: Search specific financial metrics
      description: >-
        Search for specific financial metrics across income statements, balance sheets, and cash flow statements for a
        list of tickers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLineItemsRequest'
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialsSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/financials/search/screener:
    post:
      summary: Search financial statements
      description: >-
        Search for stocks by filtering across financial metrics from income statements, balance sheets, and cash flow
        statements.
      operationId: stockScreener
      tags:
        - Financials
        - Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchFiltersRequest'
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialsSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
        - bearerAuth: []
  /apis/v1/financials/segmented-revenues:
    get:
      tags:
        - Financial Statements
      operationId: getSegmentedRevenues
      summary: Get segmented revenue data (deprecated)
      description: Deprecated. Use /financials/income-statements/segments instead.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol. Required if cik is not provided.
          required: false
          schema:
            type: string
        - name: period
          in: query
          description: The date or time period to which the reported revenue data relates in ISO 8601 format (YYYY-MM-DD).
          required: true
          schema:
            type: string
            enum:
              - annual
              - quarterly
        - name: limit
          in: query
          description: The maximum number of revenue statements to return.
          schema:
            type: integer
            format: int32
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/ReportPeriod'
        - $ref: '#/components/parameters/ReportPeriodGte'
        - $ref: '#/components/parameters/ReportPeriodLte'
        - $ref: '#/components/parameters/ReportPeriodGt'
        - $ref: '#/components/parameters/ReportPeriodLt'
      responses:
        '200':
          description: Segmented revenue response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentedRevenuesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      deprecated: true
  /apis/v1/insider-trades:
    get:
      tags:
        - Insider Trades
      operationId: getInsiderTrades
      summary: Get insider trades
      description: Get insider trades like buys and sells for a ticker by a company insider.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol of the company.
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: 'The maximum number of transactions to return (default: 10).'
          required: false
          schema:
            type: integer
            default: 10
        - name: name
          in: query
          description: >-
            Filter by insider name (e.g., 'Jen Hsun Huang'). Use the /insider-trades/names endpoint to get available
            names for a ticker.
          required: false
          schema:
            type: string
        - name: transaction_type
          in: query
          description: >-
            Filter by transaction type (e.g., 'Open market sale', 'Gift'). Use the /insider-trades/transaction-types
            endpoint to get available types.
          required: false
          schema:
            type: string
        - name: filing_date
          in: query
          description: Filter by exact filing date in YYYY-MM-DD format.
          required: false
          schema:
            type: string
            format: date
        - name: filing_date_gte
          in: query
          description: Filter by filing date greater than or equal to this date (YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: filing_date_lte
          in: query
          description: Filter by filing date less than or equal to this date (YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: filing_date_gt
          in: query
          description: Filter by filing date greater than this date (YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: filing_date_lt
          in: query
          description: Filter by filing date less than this date (YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Insider trades response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsiderTradesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/institutional-ownership:
    get:
      tags:
        - Institutional Ownership
      operationId: getInstitutionalOwnership
      summary: Get the equity holdings of an investment manager
      description: Get institutional ownership by investor or ticker. Requires either investor or ticker parameter, but not both.
      parameters:
        - name: investor
          in: query
          description: The name of the investment manager
          schema:
            type: string
        - name: ticker
          in: query
          description: The ticker symbol, if queried by investor.
          schema:
            type: string
        - name: limit
          in: query
          description: 'The maximum number of holdings to return (default: 10).'
          required: false
          schema:
            type: integer
            default: 10
        - $ref: '#/components/parameters/ReportPeriod'
        - $ref: '#/components/parameters/ReportPeriodGte'
        - $ref: '#/components/parameters/ReportPeriodLte'
        - $ref: '#/components/parameters/ReportPeriodGt'
        - $ref: '#/components/parameters/ReportPeriodLt'
      responses:
        '200':
          description: Institutional ownership response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstitutionalOwnershipResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/kalshi/market-price/{market_ticker}:
    parameters:
      - name: market_ticker
        in: path
        required: true
        description: The market ticker for the Kalshi market
        schema:
          type: string
          example: KXNFLGAME-25AUG16ARIDEN-ARI
    get:
      summary: Get Kalshi Market Price
      description: >-
        Fetches the current market price for a Kalshi market by `market_ticker`. When `at_time` is not provided, returns
        the most real-time price available. When `at_time` is provided, returns the historical market price at that
        specific timestamp. Returns prices for both yes and no sides.


        **Example Request (with historical timestamp):**

        ```bash

        curl 'https://api.domeapi.io/v1/kalshi/market-price/KXNFLGAME-25AUG16ARIDEN-ARI?at_time=1762164600' \
          -H 'Authorization: Bearer YOUR_TOKEN'
        ```


        **Example Request (real-time price):**

        ```bash

        curl 'https://api.domeapi.io/v1/kalshi/market-price/KXNFLGAME-25AUG16ARIDEN-ARI' \
          -H 'Authorization: Bearer YOUR_TOKEN'
        ```
      operationId: get_kalshi-market-price
      parameters:
        - name: at_time
          in: query
          required: false
          description: >-
            Optional Unix timestamp (in seconds) to fetch a historical market price. If not provided, returns the most
            real-time price available.
          schema:
            type: integer
            example: 1762164600
      responses:
        '200':
          description: Market price response
          content:
            application/json:
              schema:
                type: object
                properties:
                  'yes':
                    type: object
                    description: Yes side price information
                    properties:
                      price:
                        type: number
                        description: The yes side price in dollars (between 0 and 1)
                        example: 0.75
                      at_time:
                        type: integer
                        description: The timestamp for which the price was fetched (Unix timestamp in seconds)
                        example: 1762164600
                    required:
                      - price
                      - at_time
                  'no':
                    type: object
                    description: No side price information
                    properties:
                      price:
                        type: number
                        description: The no side price in dollars (between 0 and 1)
                        example: 0.25
                      at_time:
                        type: integer
                        description: The timestamp for which the price was fetched (Unix timestamp in seconds)
                        example: 1762164600
                    required:
                      - price
                      - at_time
                required:
                  - 'yes'
                  - 'no'
              examples:
                with_at_time:
                  summary: Historical price lookup
                  description: Response when `at_time` parameter is provided
                  value:
                    'yes':
                      price: 0.75
                      at_time: 1762164600
                    'no':
                      price: 0.25
                      at_time: 1762164600
                real_time:
                  summary: Real-time price lookup
                  description: Response when `at_time` parameter is omitted (most recent price)
                  value:
                    'yes':
                      price: 0.82
                      at_time: 1757008834
                    'no':
                      price: 0.18
                      at_time: 1757008834
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid at_time parameter
                  message:
                    type: string
                    example: at_time must be a valid Unix timestamp in seconds
        '404':
          description: Not Found - Market not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
                  message:
                    type: string
                    example: No price data found for market_ticker KXNFLGAME-25AUG16ARIDEN-ARI
      tags:
        - Prediction Markets
  /apis/v1/kalshi/markets:
    get:
      summary: Get Kalshi Markets
      description: >-
        Fetches Kalshi market data with optional filtering by market ticker, event ticker, status, and volume. Returns
        markets with details including pricing, volume, and status information.
      operationId: get_kalshi-markets
      parameters:
        - name: market_ticker
          in: query
          required: false
          description: Filter markets by market ticker(s). Can provide multiple values.
          schema:
            type: array
            items:
              type: string
            example:
              - KXMAYORNYCPARTY-25-D
          style: form
          explode: true
        - name: event_ticker
          in: query
          required: false
          description: Filter markets by event ticker(s). Can provide multiple values.
          schema:
            type: array
            items:
              type: string
            example:
              - KXMAYORNYCPARTY-25
          style: form
          explode: true
        - name: search
          in: query
          required: false
          description: >-
            Search markets by keywords in title and description. Must be URL encoded (e.g., 'bitcoin%20price' for
            'bitcoin price').
          schema:
            type: string
            example: bitcoin
        - name: status
          in: query
          required: false
          description: Filter markets by status (whether they're open or closed)
          schema:
            type: string
            enum:
              - open
              - closed
            example: open
        - name: min_volume
          in: query
          required: false
          description: Filter markets with total trading volume greater than or equal to this amount (in dollars)
          schema:
            type: number
            example: 10000000
        - name: limit
          in: query
          required: false
          description: 'Number of markets to return (1-100). Default: 10.'
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            example: 20
        - name: pagination_key
          in: query
          required: false
          description: Base64-encoded cursor for efficient pagination. Returned in the previous response's pagination object.
          schema:
            type: string
            example: >-
              eyJvcGVuX3RpbWUiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJtYXJrZXRfdGlja2VyIjoiS1hNQVlPUk5ZQ1BBUlRZLTI1LUQiLCJ0b3RhbCI6MTUwfQ==
      responses:
        '200':
          description: Kalshi markets response with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  markets:
                    type: array
                    items:
                      type: object
                      properties:
                        event_ticker:
                          type: string
                          description: The Kalshi event ticker
                          example: KXMAYORNYCPARTY-25
                        market_ticker:
                          type: string
                          description: The Kalshi market ticker
                          example: KXMAYORNYCPARTY-25-D
                        title:
                          type: string
                          description: Market question/title
                          example: Will a representative of the Democratic party win the NYC Mayor race in 2025?
                        start_time:
                          type: integer
                          description: Unix timestamp in seconds when the market opens
                          example: 1731150000
                        end_time:
                          type: integer
                          description: Unix timestamp in seconds when the market is scheduled to end
                          example: 1793775600
                        close_time:
                          type: integer
                          nullable: true
                          description: >-
                            Unix timestamp in seconds when the market actually resolves/closes (may be before end_time
                            if market finishes early, null if not yet closed)
                          example: 1793775600
                        status:
                          type: string
                          description: Market status
                          enum:
                            - open
                            - closed
                          example: open
                        last_price:
                          type: number
                          description: Last traded price in cents
                          example: 89
                        volume:
                          type: number
                          description: Total trading volume in dollars
                          example: 18261146
                        volume_24h:
                          type: number
                          description: 24-hour trading volume in dollars
                          example: 931138
                        result:
                          type: string
                          nullable: true
                          description: Market result (null if unresolved)
                          example: null
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        description: Total number of markets matching the filters
                        example: 150
                      has_more:
                        type: boolean
                        description: Whether there are more markets available
                        example: true
                      pagination_key:
                        type: string
                        description: Base64-encoded cursor for the next page. Only present when there are more results.
                        example: >-
                          eyJvcGVuX3RpbWUiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJtYXJrZXRfdGlja2VyIjoiS1hNQVlPUk5ZQ1BBUlRZLTI1LUQiLCJ0b3RhbCI6MTUwfQ==
        '400':
          description: Bad Request - Invalid parameters or validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid limit parameter
                  message:
                    type: string
                    example: limit must be a number between 1 and 100
      tags:
        - Prediction Markets
  /apis/v1/kalshi/orderbooks:
    get:
      summary: Get Kalshi Orderbook History
      description: >-
        Fetches historical orderbook snapshots for a specific Kalshi market (ticker) over a specified time range. If no
        start_time and end_time are provided, returns the latest orderbook snapshot for the market. Returns snapshots of
        the order book including yes/no bids and asks with prices in both cents and dollars. All timestamps are in
        milliseconds. Orderbook data has history starting from October 29th, 2025. Note: When fetching the latest
        orderbook (without start/end times), the limit parameter is ignored.
      operationId: get_kalshi-orderbooks
      parameters:
        - name: ticker
          in: query
          required: true
          description: The Kalshi market ticker
          schema:
            type: string
            example: KXNFLGAME-25AUG16ARIDEN-ARI
        - name: start_time
          in: query
          required: false
          description: >-
            Start time in Unix timestamp (milliseconds). Optional - if not provided along with end_time, returns the
            latest orderbook snapshot.
          schema:
            type: integer
            example: 1760470000000
        - name: end_time
          in: query
          required: false
          description: >-
            End time in Unix timestamp (milliseconds). Optional - if not provided along with start_time, returns the
            latest orderbook snapshot.
          schema:
            type: integer
            example: 1760480000000
        - name: limit
          in: query
          required: false
          description: >-
            Maximum number of snapshots to return (default: 100, max: 200). Ignored when fetching the latest orderbook
            without start_time and end_time.
          schema:
            type: integer
            default: 100
            maximum: 200
            example: 100
        - name: paginationKey
          in: query
          required: false
          description: Base64-encoded cursor for efficient pagination. Returned in the previous response's pagination object.
          schema:
            type: string
            example: eyJ0aW1lc3RhbXAiOjE3NjA0NzAwMDAwMDAsInRpY2tlciI6IktYTkZMR0FNRS0yNUFVRzE2QVJJREVOLUFSSSIsInRvdGFsIjoxMDB9
      responses:
        '200':
          description: Kalshi orderbook history response
          content:
            application/json:
              schema:
                type: object
                properties:
                  snapshots:
                    type: array
                    description: Array of orderbook snapshots at different points in time
                    items:
                      type: object
                      properties:
                        orderbook:
                          type: object
                          properties:
                            'yes':
                              type: array
                              description: Yes side orders with prices in cents
                              items:
                                type: array
                                description: '[price_in_cents, contract_count]'
                                items:
                                  type: number
                                minItems: 2
                                maxItems: 2
                                example:
                                  - 75
                                  - 100
                            'no':
                              type: array
                              description: No side orders with prices in cents
                              items:
                                type: array
                                description: '[price_in_cents, contract_count]'
                                items:
                                  type: number
                                minItems: 2
                                maxItems: 2
                                example:
                                  - 25
                                  - 100
                            yes_dollars:
                              type: array
                              description: Yes side orders with prices in dollars
                              items:
                                type: array
                                description: '[price_as_dollar_string, contract_count]'
                                minItems: 2
                                maxItems: 2
                                items:
                                  oneOf:
                                    - type: string
                                    - type: number
                                example:
                                  - '0.75'
                                  - 100
                            no_dollars:
                              type: array
                              description: No side orders with prices in dollars
                              items:
                                type: array
                                description: '[price_as_dollar_string, contract_count]'
                                minItems: 2
                                maxItems: 2
                                items:
                                  oneOf:
                                    - type: string
                                    - type: number
                                example:
                                  - '0.25'
                                  - 100
                        timestamp:
                          type: integer
                          description: Timestamp of the snapshot in milliseconds
                          example: 1760471849407
                        ticker:
                          type: string
                          description: The Kalshi market ticker
                          example: KXNFLGAME-25AUG16ARIDEN-ARI
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        example: 100
                      count:
                        type: integer
                        description: Number of snapshots returned
                        example: 4
                      paginationKey:
                        type: string
                        description: >-
                          Base64-encoded cursor for fetching the next page of results. Only present when has_more is
                          true.
                        example: >-
                          eyJ0aW1lc3RhbXAiOjE3NjA0NzAwMDAwMDAsInRpY2tlciI6IktYTkZMR0FNRS0yNUFVRzE2QVJJREVOLUFSSSIsInRvdGFsIjoxMDB9
                      has_more:
                        type: boolean
                        description: Whether there are more snapshots available
                        example: false
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid parameters
                  message:
                    type: string
                    example: ticker, start_time, and end_time are required
      tags:
        - Prediction Markets
  /apis/v1/kalshi/trades:
    get:
      summary: Get Kalshi Trades
      description: >-
        Fetches historical trade data for Kalshi markets with optional filtering by ticker and time range. Returns
        executed trades with pricing, volume, and taker side information. All timestamps are in seconds.
      operationId: get_kalshi-trades
      parameters:
        - name: ticker
          in: query
          required: false
          description: The Kalshi market ticker to filter trades
          schema:
            type: string
            example: KXNFLGAME-25NOV09PITLAC-PIT
        - name: start_time
          in: query
          required: false
          description: Start time in Unix timestamp (seconds)
          schema:
            type: integer
            example: 1762716000
        - name: end_time
          in: query
          required: false
          description: End time in Unix timestamp (seconds)
          schema:
            type: integer
            example: 1762720600
        - name: limit
          in: query
          required: false
          description: 'Maximum number of trades to return (default: 100)'
          schema:
            type: integer
            default: 100
            example: 10
        - name: pagination_key
          in: query
          required: false
          description: Base64-encoded cursor for efficient pagination. Returned in the previous response's pagination object.
          schema:
            type: string
            example: >-
              eyJjcmVhdGVkX3RpbWUiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJ0cmFkZV9pZCI6IjEyMzQ1Njc4OTAiLCJ0b3RhbCI6NTAwMDB9
      responses:
        '200':
          description: Kalshi trades response with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  trades:
                    type: array
                    description: Array of executed trades
                    items:
                      type: object
                      properties:
                        trade_id:
                          type: string
                          description: Unique identifier for the trade
                          example: 587f9eb0-1ae1-7b53-9536-fcf3fc503630
                        market_ticker:
                          type: string
                          description: The Kalshi market ticker
                          example: KXNFLGAME-25NOV09PITLAC-PIT
                        count:
                          type: integer
                          description: Number of contracts traded
                          example: 93
                        yes_price:
                          type: integer
                          description: Yes side price in cents
                          example: 1
                        no_price:
                          type: integer
                          description: No side price in cents
                          example: 99
                        yes_price_dollars:
                          type: number
                          description: Yes side price in dollars
                          example: 0.01
                        no_price_dollars:
                          type: number
                          description: No side price in dollars
                          example: 0.99
                        taker_side:
                          type: string
                          description: Which side was the taker (yes or no)
                          enum:
                            - 'yes'
                            - 'no'
                          example: 'yes'
                        created_time:
                          type: integer
                          description: Timestamp of the trade in seconds (Unix timestamp)
                          example: 1762718746
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        example: 50
                      total:
                        type: integer
                        description: Total number of trades matching the filters
                        example: 43154
                      has_more:
                        type: boolean
                        description: Whether there are more trades available
                        example: true
                      pagination_key:
                        type: string
                        description: Base64-encoded cursor for the next page. Only present when there are more results.
                        example: >-
                          eyJjcmVhdGVkX3RpbWUiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJ0cmFkZV9pZCI6IjEyMzQ1Njc4OTAiLCJ0b3RhbCI6NTAwMDB9
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid parameters
                  message:
                    type: string
                    example: Invalid time range or parameters
      tags:
        - Prediction Markets
  /apis/v1/macro/interest-rates:
    get:
      summary: Interest Rates (Historical)
      description: Historical interest rates for all major central banks in the world.
      operationId: getInterestRatesHistorical
      parameters:
        - name: bank
          in: query
          description: >-
            The bank whose interest rates to return. Use the /macro/interest-rates/banks endpoint to get a list of
            available banks.
          required: true
          schema:
            type: string
        - name: start_date
          in: query
          description: The start date of the interest rates to return in YYYY-MM-DD format.
          required: false
          schema:
            type: string
        - name: end_date
          in: query
          description: The end date of the interest rates to return in YYYY-MM-DD format.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Interest rates response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterestRatesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      tags:
        - Financial Data
  /apis/v1/macro/interest-rates/snapshot:
    get:
      summary: Interest Rates (Real-Time)
      description: Get the current interest rates from all major central banks in the world.
      operationId: getInterestRatesSnapshot
      parameters:
        - name: bank
          in: query
          description: >-
            The central bank code (e.g., FED, ECB, BOJ). Use the /macro/interest-rates/banks endpoint to get a list of
            available banks.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Interest rates snapshot response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterestRatesResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      tags:
        - Financial Data
  /apis/v1/matching-markets/sports:
    get:
      summary: Get Matching Markets for Sports
      description: >-
        Find equivalent markets across different prediction market platforms (Polymarket, Kalshi, etc.) for sports
        events. Provide either one or more Polymarket market slugs or Kalshi event tickers.
      operationId: get_matching-markets-sports
      parameters:
        - name: polymarket_market_slug
          in: query
          required: false
          description: >-
            The Polymarket market slug(s) to find matching markets for. To get multiple markets at once, provide the
            query param multiple times with different slugs. Can not be combined with kalshi_event_ticker.
          schema:
            type: array
            items:
              type: string
            example:
              - nfl-ari-den-2025-08-16
              - nfl-dal-phi-2025-09-04
          style: form
          explode: true
        - name: kalshi_event_ticker
          in: query
          required: false
          description: >-
            The Kalshi event ticker(s) to find matching markets for. To get multiple markets at once, provide the query
            param multiple times with different tickers. Can not be combined with polymarket_market_slug.
          schema:
            type: array
            items:
              type: string
            example:
              - KXNFLGAME-25AUG16ARIDEN
              - KXNFLGAME-25SEP04DALPHI
          style: form
          explode: true
      responses:
        '200':
          description: Matching markets response
          content:
            application/json:
              schema:
                type: object
                properties:
                  markets:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        oneOf:
                          - type: object
                            description: Kalshi market
                            properties:
                              platform:
                                type: string
                                enum:
                                  - KALSHI
                                example: KALSHI
                              event_ticker:
                                type: string
                                example: KXNFLGAME-25AUG16ARIDEN
                              market_tickers:
                                type: array
                                items:
                                  type: string
                                example:
                                  - KXNFLGAME-25AUG16ARIDEN-ARI
                                  - KXNFLGAME-25AUG16ARIDEN-DEN
                            required:
                              - platform
                              - event_ticker
                              - market_tickers
                          - type: object
                            description: Polymarket market
                            properties:
                              platform:
                                type: string
                                enum:
                                  - POLYMARKET
                                example: POLYMARKET
                              market_slug:
                                type: string
                                example: nfl-ari-den-2025-08-16
                              token_ids:
                                type: array
                                items:
                                  type: string
                                example:
                                  - '34541522652444763571858406546623861155130750437169507355470933750634189084033'
                                  - '104612081187206848956763018128517335758189185749897027211060738913329108425255'
                            required:
                              - platform
                              - market_slug
                              - token_ids
                    example:
                      nfl-ari-den-2025-08-16:
                        - platform: KALSHI
                          event_ticker: KXNFLGAME-25AUG16ARIDEN
                          market_tickers:
                            - KXNFLGAME-25AUG16ARIDEN-ARI
                            - KXNFLGAME-25AUG16ARIDEN-DEN
                        - platform: POLYMARKET
                          market_slug: nfl-ari-den-2025-08-16
                          token_ids:
                            - '34541522652444763571858406546623861155130750437169507355470933750634189084033'
                            - '104612081187206848956763018128517335758189185749897027211060738913329108425255'
                      nfl-dal-phi-2025-09-04:
                        - platform: KALSHI
                          event_ticker: KXNFLGAME-25SEP04DALPHI
                          market_tickers:
                            - KXNFLGAME-25SEP04DALPHI-DAL
                            - KXNFLGAME-25SEP04DALPHI-PHI
        '400':
          description: Bad Request - Missing or invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing required parameter
                  message:
                    type: string
                    example: At least one polymarket_market_slug or kalshi_event_ticker is required
        '404':
          description: Not Found - No matching markets found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not found
                  message:
                    type: string
                    example: No matching markets found for the provided parameters
      tags:
        - Prediction Markets
  /apis/v1/matching-markets/sports/{sport}:
    parameters:
      - name: sport
        in: path
        required: true
        description: |-
          The sport to find matching markets for.

          Sport abbreviations:
          - nfl = Football
          - mlb = Baseball
          - cfb = College Football
          - nba = Basketball
          - nhl = Hockey
          - cbb = College Basketball
          - pga = Golf
          - tennis = Tennis
        schema:
          type: string
          enum:
            - nfl
            - mlb
            - cfb
            - nba
            - nhl
            - cbb
            - pga
            - tennis
          example: nfl
    get:
      summary: Get Matching Markets for Sports by Sport and Date
      description: >-
        Find equivalent markets across different prediction market platforms (Polymarket, Kalshi, etc.) for sports
        events by sport and date.
      operationId: get_matching-markets-sports-by-sport
      parameters:
        - name: date
          in: query
          required: true
          description: The date to find matching markets for in YYYY-MM-DD format
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
            example: '2025-08-16'
      responses:
        '200':
          description: Matching markets response
          content:
            application/json:
              schema:
                type: object
                properties:
                  markets:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        oneOf:
                          - type: object
                            description: Kalshi market
                            properties:
                              platform:
                                type: string
                                enum:
                                  - KALSHI
                                example: KALSHI
                              event_ticker:
                                type: string
                                example: KXNFLGAME-25AUG16ARIDEN
                              market_tickers:
                                type: array
                                items:
                                  type: string
                                example:
                                  - KXNFLGAME-25AUG16ARIDEN-ARI
                                  - KXNFLGAME-25AUG16ARIDEN-DEN
                            required:
                              - platform
                              - event_ticker
                              - market_tickers
                          - type: object
                            description: Polymarket market
                            properties:
                              platform:
                                type: string
                                enum:
                                  - POLYMARKET
                                example: POLYMARKET
                              market_slug:
                                type: string
                                example: nfl-ari-den-2025-08-16
                              token_ids:
                                type: array
                                items:
                                  type: string
                                example:
                                  - '34541522652444763571858406546623861155130750437169507355470933750634189084033'
                                  - '104612081187206848956763018128517335758189185749897027211060738913329108425255'
                            required:
                              - platform
                              - market_slug
                              - token_ids
                    example:
                      nfl-ari-den-2025-08-16:
                        - platform: KALSHI
                          event_ticker: KXNFLGAME-25AUG16ARIDEN
                          market_tickers:
                            - KXNFLGAME-25AUG16ARIDEN-ARI
                            - KXNFLGAME-25AUG16ARIDEN-DEN
                        - platform: POLYMARKET
                          market_slug: nfl-ari-den-2025-08-16
                          token_ids:
                            - '34541522652444763571858406546623861155130750437169507355470933750634189084033'
                            - '104612081187206848956763018128517335758189185749897027211060738913329108425255'
                  sport:
                    type: string
                    example: nfl
                  date:
                    type: string
                    example: '2025-08-16'
        '400':
          description: Bad Request - Missing or invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing required parameter
                  message:
                    type: string
                    example: date parameter is required
      tags:
        - Prediction Markets
  /apis/v1/news:
    get:
      tags:
        - News
      operationId: getNews
      summary: Get news articles
      description: >-
        Get recent news articles for a specific company or the broad market. Pass a ticker for company-specific news, or
        omit the ticker for general market news. Articles are sourced from RSS feeds of publishers like The Motley Fool,
        Investing.com, Reuters, and more.
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol of the company. Omit for broad market news.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: 'The maximum number of news articles to return (default: 5, max: 10).'
          required: false
          schema:
            type: integer
            default: 5
            maximum: 10
      responses:
        '200':
          description: News articles response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/oapi/my/info: {}
  /apis/v1/perplexity/sonar:
    post:
      tags:
        - Perplexity Sonar
      operationId: post_perplexity-sonar
      summary: Sonar — lightweight search + answer
      description: >-
        Cost-effective model for quick web searches with AI-generated answers. Best for simple factual queries. Uses
        model `sonar`.


        **Pricing:** $0.012 per request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: sonar
              messages:
                - role: user
                  content: What are the latest developments in quantum computing?
      responses:
        '200':
          description: Successful response with AI answer and citations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
  /apis/v1/perplexity/sonar-deep-research:
    post:
      tags:
        - Perplexity Deep Research
      operationId: post_perplexity-sonar-deep-research
      summary: Sonar Deep Research — exhaustive research & comprehensive reports
      description: >-
        Expert-level research model that conducts exhaustive multi-step web searches and generates comprehensive
        reports. Best for deep-dive research tasks. Uses model `sonar-deep-research`.


        **Pricing:** $0.012 per request


        > **Note:** Deep research requests may take significantly longer to complete due to the exhaustive search
        process.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: sonar-deep-research
              messages:
                - role: user
                  content: Write a comprehensive analysis of the global semiconductor supply chain risks in 2026
      responses:
        '200':
          description: Successful response with AI answer and citations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
  /apis/v1/perplexity/sonar-pro:
    post:
      tags:
        - Perplexity Sonar Pro
      operationId: post_perplexity-sonar-pro
      summary: Sonar Pro — advanced search for complex queries
      description: >-
        Advanced search model supporting complex queries and multi-step follow-ups. Better for nuanced research
        questions. Uses model `sonar-pro`.


        **Pricing:** $0.012 per request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: sonar-pro
              messages:
                - role: user
                  content: Compare the economic policies of the US and EU regarding AI regulation in 2025-2026
      responses:
        '200':
          description: Successful response with AI answer and citations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
  /apis/v1/perplexity/sonar-reasoning-pro:
    post:
      tags:
        - Perplexity Sonar Reasoning
      operationId: post_perplexity-sonar-reasoning-pro
      summary: Sonar Reasoning Pro — chain-of-thought reasoning with search
      description: >-
        Reasoning model with Chain of Thought (CoT) for precise, step-by-step analysis backed by web search. Best for
        analytical and complex reasoning tasks. Uses model `sonar-reasoning-pro`.


        **Pricing:** $0.012 per request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: sonar-reasoning-pro
              messages:
                - role: user
                  content: Analyze whether Tesla stock is overvalued based on current P/E ratio compared to industry averages
      responses:
        '200':
          description: Successful response with AI answer and citations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
  /apis/v1/polymarket/activity:
    get:
      summary: Get Activity
      description: >-
        Fetches activity data with optional filtering by user, market, condition, and time range. Returns trading
        activity including `MERGES`, `SPLITS`, and `REDEEMS`. Supports efficient cursor-based pagination for large
        datasets.
      operationId: get_polymarket-activity
      parameters:
        - name: user
          in: query
          required: false
          description: User wallet address to fetch activity for. If not provided, returns activity for all users.
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
            example: '0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b'
        - name: start_time
          in: query
          required: false
          description: Filter activity from this Unix timestamp in seconds (inclusive)
          schema:
            type: integer
            example: 1640995200
        - name: end_time
          in: query
          required: false
          description: Filter activity until this Unix timestamp in seconds (inclusive)
          schema:
            type: integer
            example: 1672531200
        - name: market_slug
          in: query
          required: false
          description: Filter activity by market slug
          schema:
            type: string
            example: bitcoin-up-or-down-july-25-8pm-et
        - name: condition_id
          in: query
          required: false
          description: Filter activity by condition ID
          schema:
            type: string
            example: '0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57'
        - name: limit
          in: query
          required: false
          description: Number of activities to return (1-1000)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
            example: 50
        - name: pagination_key
          in: query
          required: false
          description: Base64-encoded cursor for efficient pagination. Returned in the previous response's pagination object.
          schema:
            type: string
            example: >-
              eyJibG9ja190aW1lc3RhbXAiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJzaWRlIjoiU1BMSVQiLCJ0eF9oYXNoIjoiMHgxMjM0NTY3ODkwYWJjZGVmIiwibG9nX2luZGV4IjoxMCwidG90YWwiOjE5ODkwMTc3Nn0=
      responses:
        '200':
          description: Activity response with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  activities:
                    type: array
                    items:
                      type: object
                      properties:
                        token_id:
                          type: string
                          example: ''
                        side:
                          type: string
                          enum:
                            - MERGE
                            - SPLIT
                            - REDEEM
                          example: REDEEM
                        market_slug:
                          type: string
                          example: will-the-doj-charge-boeing
                        condition_id:
                          type: string
                          example: '0x92e4b1b8e0621fab0537486e7d527322569d7a8fd394b3098ff4bb1d6e1c0bbd'
                        shares:
                          type: number
                          example: 187722726
                          description: Raw number of shares (from the blockchain)
                        shares_normalized:
                          type: number
                          example: 187.722726
                          description: Number of shares normalized (raw divided by 1000000)
                        price:
                          type: number
                          example: 1
                        block_number:
                          type: integer
                          description: Block number where the activity occurred
                          example: 123456789
                        log_index:
                          type: integer
                          description: Log index of the activity event in the block
                          example: 42
                        tx_hash:
                          type: string
                          example: '0x028baff23a90c10728606781d15077098ee93c991ea204aa52a0bd2869187574'
                        title:
                          type: string
                          example: Will the DOJ charge Boeing?
                        timestamp:
                          type: integer
                          description: Unix timestamp in seconds when the activity occurred
                          example: 1721263049
                        order_hash:
                          type: string
                          example: ''
                        user:
                          type: string
                          description: User wallet address
                          example: '0xfd9c3e7f8c56eb4186372f343c873cce154b3873'
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        example: 50
                      count:
                        type: integer
                        description: Total number of activities matching the filters
                        example: 1250
                      has_more:
                        type: boolean
                        description: Whether there are more activities available
                        example: true
                      pagination_key:
                        type: string
                        description: Base64-encoded cursor for the next page. Only present when there are more results.
                        example: >-
                          eyJibG9ja190aW1lc3RhbXAiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJzaWRlIjoiU1BMSVQiLCJ0eF9oYXNoIjoiMHgxMjM0NTY3ODkwYWJjZGVmIiwibG9nX2luZGV4IjoxMCwidG90YWwiOjE5ODkwMTc3Nn0=
        '400':
          description: Bad Request - Invalid parameters or validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing required parameter
                  message:
                    type: string
                    example: user parameter is required
              examples:
                invalid_start_time:
                  summary: Invalid start_time parameter
                  value:
                    error: Invalid start_time parameter
                    message: start_time must be a valid Unix timestamp
                invalid_end_time:
                  summary: Invalid end_time parameter
                  value:
                    error: Invalid end_time parameter
                    message: end_time must be a valid Unix timestamp
                invalid_time_range:
                  summary: Invalid time range
                  value:
                    error: Invalid time range
                    message: start_time must be less than end_time
                invalid_limit:
                  summary: Invalid limit
                  value:
                    error: Invalid limit parameter
                    message: limit must be a number between 1 and 1000
                invalid_pagination_key:
                  summary: Invalid pagination key
                  value:
                    error: Invalid pagination key
                    message: pagination_key is invalid or corrupted
                invalid_filter_combination:
                  summary: Invalid filter combination
                  value:
                    error: Invalid filter combination
                    message: Only one of market_slug or condition_id can be provided
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal Server Error
                  message:
                    type: string
                    example: Failed to fetch activity data
      tags:
        - Prediction Markets
  /apis/v1/polymarket/candlesticks:
    parameters:
      - name: condition_id
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Get Candlesticks
      description: Fetches historical candlestick data for a market identified by `condition_id`, over a specified interval.
      operationId: get_polymarket-candlesticks
      parameters:
        - name: condition_id
          in: query
          required: true
          description: Polymarket condition ID for the market.
          schema:
            type: string
          example: '0x1234abcd5678ef90'
        - name: start_time
          in: query
          required: true
          description: Unix timestamp (in seconds) for start of time range
          schema:
            type: integer
            example: 1640995200
        - name: end_time
          in: query
          required: true
          description: Unix timestamp (in seconds) for end of time range
          schema:
            type: integer
            example: 1672531200
        - name: interval
          in: query
          required: false
          description: |+
            Interval length: 1 = 1m, 60 = 1h, 1440 = 1d. Defaults to 1m. 

            ⚠️ **Note:** There are range limits for `interval` — specifically:
            - `1` (1m): max range **1 week**
            - `60` (1h): max range **1 month**
            - `1440` (1d): max range **1 year**

          schema:
            type: integer
            enum:
              - 1
              - 60
              - 1440
            default: 1
      responses:
        '200':
          description: Candlestick response
          content:
            application/json:
              schema:
                type: object
                properties:
                  candlesticks:
                    type: array
                    description: >-
                      Array of market candlestick data, where each element is a tuple containing candlestick data array
                      and token metadata
                    items:
                      type: array
                      description: Tuple of [candlestick_data_array, token_metadata]
                      minItems: 2
                      maxItems: 2
                      items:
                        oneOf:
                          - type: array
                            description: Candlestick data array
                            items:
                              type: object
                          - type: object
                            description: Token metadata
                            properties:
                              token_id:
                                type: string
                              side:
                                type: string
                                description: >-
                                  The outcome label for this token (e.g., 'Yes', 'No', 'Up', 'Down', 'Over', 'Under', or
                                  team names for sports markets)
                      example:
                        - - end_period_ts: 1727827200
                            open_interest: 8456498
                            price:
                              open: 0
                              high: 0
                              low: 0
                              close: 0
                              open_dollars: '0.0049'
                              high_dollars: '0.0049'
                              low_dollars: '0.0048'
                              close_dollars: '0.0048'
                              mean: 0
                              mean_dollars: '0.0049'
                              previous: 0
                              previous_dollars: '0.0049'
                            volume: 8456498
                            yes_ask:
                              open: 0.00489
                              close: 0.0048200000000000005
                              high: 0.00491
                              low: 0.0048
                              open_dollars: '0.0049'
                              close_dollars: '0.0048'
                              high_dollars: '0.0049'
                              low_dollars: '0.0048'
                            yes_bid:
                              open: 0.00489
                              close: 0.004829999990880811
                              high: 0.004910000000138527
                              low: 0.0048
                              open_dollars: '0.0049'
                              close_dollars: '0.0048'
                              high_dollars: '0.0049'
                              low_dollars: '0.0048'
                        - token_id: '21742633143463906290569050155826241533067272736897614950488156847949938836455'
                          side: 'Yes'
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing required query parameters
                  required:
                    type: string
                    example: start_time, end_time
      tags:
        - Prediction Markets
  /apis/v1/polymarket/candlesticks/{condition_id}:
    get:
      summary: OHLC candlestick data with volume, open interest, bid/ask spread
      description: Auto-generated stub from Prediction Market Data skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getPolymarketCandlesticksConditionId
      tags:
        - Prediction Markets
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/polymarket/events:
    get:
      summary: Get Events
      description: >-
        Fetches events (groups of related markets) with optional filtering by event_slug, tags/categories and status.
        Events aggregate multiple markets under a single topic (e.g., 'Presidential Election 2024' contains multiple
        candidate markets). Returns events ordered by total volume (most popular first).


        **Example Request (single event by slug):**

        ```bash

        curl
        'https://api.aisa.one/apis/v1/polymarket/events?event_slug=presidential-election-winner-2024&include_markets=true'

        ```


        **Example Request (filter by tags):**

        ```bash

        curl 'https://api.aisa.one/apis/v1/polymarket/events?tags=sports&status=open&limit=10'

        ```


        **Example Request (with markets included):**

        ```bash

        curl 'https://api.aisa.one/apis/v1/polymarket/events?include_markets=true&limit=5'

        ```
      operationId: get_polymarket-events
      parameters:
        - name: event_slug
          in: query
          required: false
          description: >-
            Filter by specific event slug. When provided, returns a single hydrated event matching that slug (e.g.,
            'presidential-election-winner-2024'). Use with include_markets=true to get the full event with all its
            markets.
          schema:
            type: string
            example: presidential-election-winner-2024
        - name: tags
          in: query
          required: false
          description: Filter events by tag(s)/category. Can provide multiple values (e.g., sports, crypto, politics).
          schema:
            type: array
            items:
              type: string
            example:
              - sports
              - football
          style: form
          explode: true
        - name: status
          in: query
          required: false
          description: >-
            Filter events by status. An event is 'open' if any of its markets are still open, 'closed' if all markets
            are closed.
          schema:
            type: string
            enum:
              - open
              - closed
            example: open
        - name: include_markets
          in: query
          required: false
          description: Set to 'true' to include the list of markets for each event in the response.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
            example: 'true'
        - name: start_time
          in: query
          required: false
          description: Filter events starting after this Unix timestamp (seconds)
          schema:
            type: integer
            example: 1640995200
        - name: end_time
          in: query
          required: false
          description: Filter events starting before this Unix timestamp (seconds)
          schema:
            type: integer
            example: 1672531200
        - name: game_start_time
          in: query
          required: false
          description: >-
            Filter events by game start time (Unix timestamp in seconds). Useful for filtering sports events by when the
            game starts.
          schema:
            type: integer
            example: 1704067200
        - name: limit
          in: query
          required: false
          description: 'Number of events to return (1-100). Default: 10.'
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            example: 10
        - name: pagination_key
          in: query
          required: false
          description: >-
            Pagination key for cursor-based pagination. Use the value from the previous response's
            pagination.pagination_key field to get the next page of results. Do not use the deprecated 'offset'
            parameter.
          schema:
            type: string
            example: eyJsYXN0Vm9sdW1lIjoxNzEyMTMyNjYzLjk2MTYwNjMsImxhc3RFdmVudFNsdWciOiJuYmEtY2hhbXBpb24tMjAyNC0yMDI1In0=
      responses:
        '200':
          description: Events response with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        event_slug:
                          type: string
                          description: Unique identifier for the event
                          example: presidential-election-winner-2024
                        title:
                          type: string
                          description: Event title
                          example: Presidential Election Winner 2024
                        subtitle:
                          type: string
                          nullable: true
                          description: Event subtitle or description
                          example: Who will win the 2024 US Presidential Election?
                        status:
                          type: string
                          enum:
                            - open
                            - closed
                          description: Event status - 'open' if any market is open, 'closed' if all markets are closed
                          example: closed
                        start_time:
                          type: integer
                          description: Unix timestamp (seconds) when the event started
                          example: 1704067200
                        end_time:
                          type: integer
                          description: Unix timestamp (seconds) when the event ends
                          example: 1730851200
                        volume_fiat_amount:
                          type: number
                          description: Total trading volume across all markets in the event (USD)
                          example: 3686335059.29
                        settlement_sources:
                          type: string
                          nullable: true
                          description: Resolution/settlement source for the event
                          example: Associated Press
                        rules_url:
                          type: string
                          nullable: true
                          description: URL to the event rules (if available)
                          example: null
                        image:
                          type: string
                          nullable: true
                          description: Event image URL
                          example: https://polymarket.com/images/election-2024.png
                        tags:
                          type: array
                          items:
                            type: string
                          description: Array of category tags for the event
                          example:
                            - politics
                            - elections
                        market_count:
                          type: integer
                          description: Number of markets in this event
                          example: 17
                        markets:
                          type: array
                          description: List of markets in this event (only included when include_markets=true)
                          items:
                            type: object
                            properties:
                              market_slug:
                                type: string
                                example: will-trump-win-2024
                              title:
                                type: string
                                example: Will Trump win the 2024 election?
                              condition_id:
                                type: string
                                example: 0x1234...
                              status:
                                type: string
                                enum:
                                  - open
                                  - closed
                                example: closed
                              volume_total:
                                type: number
                                example: 1500000000
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        description: Number of events returned in this response
                        example: 10
                      has_more:
                        type: boolean
                        description: Whether there are more events available. If true, use pagination_key to fetch the next page.
                        example: true
                      pagination_key:
                        type: string
                        nullable: true
                        description: >-
                          Pagination key for fetching the next page. Pass this value as the pagination_key query
                          parameter to get the next page of results. Will be null if has_more is false.
                        example: >-
                          eyJsYXN0Vm9sdW1lIjoxNzEyMTMyNjYzLjk2MTYwNjMsImxhc3RFdmVudFNsdWciOiJuYmEtY2hhbXBpb24tMjAyNC0yMDI1In0=
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid status parameter
                  message:
                    type: string
                    example: status must be 'open' or 'closed'
              examples:
                invalid_status:
                  summary: Invalid status
                  value:
                    error: Invalid status parameter
                    message: status must be 'open' or 'closed'
                invalid_limit:
                  summary: Invalid limit
                  value:
                    error: Invalid limit parameter
                    message: limit must be a number between 1 and 100
                invalid_offset:
                  summary: Invalid offset
                  value:
                    error: Invalid offset parameter
                    message: offset must be a non-negative number
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal Server Error
                  message:
                    type: string
                    example: Failed to fetch events data
      tags:
        - Prediction Markets
  /apis/v1/polymarket/market-price/{token_id}:
    parameters:
      - name: token_id
        in: path
        required: true
        description: The token ID for the Polymarket market
        schema:
          type: string
          example: '19701256321759583954581192053894521654935987478209343000964756587964612528044'
    get:
      summary: Get Market Price
      description: >-
        Fetches the current market price for a market by `token_id`. When `at_time` is not provided, returns the most
        real-time price available. When `at_time` is provided, returns the historical market price at that specific
        timestamp.


        **Example Request (with historical timestamp):**

        ```bash

        curl
        'https://api.aisa.one/apis/v1/polymarket/market-price/19701256321759583954581192053894521654935987478209343000964756587964612528044?at_time=1762164600'

        ```


        **Example Request (real-time price):**

        ```bash

        curl
        'https://api.aisa.one/apis/v1/polymarket/market-price/19701256321759583954581192053894521654935987478209343000964756587964612528044'

        ```
      operationId: get_polymarket-market-price
      parameters:
        - name: at_time
          in: query
          required: false
          description: >-
            Optional Unix timestamp (in seconds) to fetch a historical market price. If not provided, returns the most
            real-time price available.
          schema:
            type: integer
            example: 1762164600
      responses:
        '200':
          description: Market price response
          content:
            application/json:
              schema:
                type: object
                properties:
                  price:
                    type: number
                    description: The market price (between 0 and 1)
                    example: 0.999
                  at_time:
                    type: integer
                    description: The timestamp for which the price was fetched (Unix timestamp in seconds)
                    example: 1762164600
                required:
                  - price
                  - at_time
              examples:
                with_at_time:
                  summary: Historical price lookup
                  description: Response when `at_time` parameter is provided
                  value:
                    price: 0.999
                    at_time: 1762164600
                real_time:
                  summary: Real-time price lookup
                  description: Response when `at_time` parameter is omitted (most recent price)
                  value:
                    price: 0.215
                    at_time: 1757008834
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid token_id
                  message:
                    type: string
                    example: token_id must be a valid string
        '404':
          description: Not Found - Market not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not found
                  message:
                    type: string
                    example: Market with the provided token_id not found
      tags:
        - Prediction Markets
  /apis/v1/polymarket/markets:
    get:
      summary: Get Markets
      description: >-
        Fetches market data with optional filtering and search functionality. Supports filtering by market slug,
        condition ID, token ID, or tags, as well as fuzzy search across market titles and descriptions. Returns markets
        ordered by volume (most popular first) when filters are applied, or by start_time (most recent first) when no
        filters are provided.
      operationId: get_polymarket-markets
      parameters:
        - name: market_slug
          in: query
          required: false
          description: Filter markets by market slug(s). Can provide multiple values.
          schema:
            type: array
            items:
              type: string
            example:
              - bitcoin-up-or-down-july-25-8pm-et
          style: form
          explode: true
        - name: event_slug
          in: query
          required: false
          description: Filter markets by event slug(s). Can provide multiple values.
          schema:
            type: array
            items:
              type: string
            example:
              - presidential-election-winner-2028
          style: form
          explode: true
        - name: condition_id
          in: query
          required: false
          description: Filter markets by condition ID(s). Can provide multiple values.
          schema:
            type: array
            items:
              type: string
            example:
              - '0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57'
          style: form
          explode: true
        - name: token_id
          in: query
          required: false
          description: >-
            Filter markets by token ID(s). Matches markets where the token_id is either the primary_token_id or
            secondary_token_id. Can provide multiple values (maximum 100). Each token_id must be a numeric string.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9]+$
            maxItems: 100
            example:
              - '24891147099018724959141647991382271578149113344000019968758330059825991230807'
          style: form
          explode: true
        - name: tags
          in: query
          required: false
          description: Filter markets by tag(s). Can provide multiple values.
          schema:
            type: array
            items:
              type: string
            example:
              - politics
              - crypto
          style: form
          explode: true
        - name: search
          in: query
          required: false
          description: >-
            Search markets by keywords in title and description. Must be URL encoded (e.g., 'bitcoin%20price' for
            'bitcoin price').
          schema:
            type: string
            example: bitcoin
        - name: status
          in: query
          required: false
          description: Filter markets by status (whether they're open or closed)
          schema:
            type: string
            enum:
              - open
              - closed
            example: open
        - name: min_volume
          in: query
          required: false
          description: Filter markets with total trading volume greater than or equal to this amount (USD)
          schema:
            type: number
            example: 100000
        - name: limit
          in: query
          required: false
          description: 'Number of markets to return (1-100). Default: 10 for search, 10 for regular queries.'
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            example: 20
        - name: pagination_key
          in: query
          required: false
          description: >-
            Base64-encoded cursor for efficient pagination. Returned in the previous response's pagination object. Use
            this instead of large offsets for better performance.
          schema:
            type: string
            example: eyJzdGFydF9kYXRlIjoiMjAyNi0wMS0xOVQxMjowMDowMC4wMDBaIiwiY29uZGl0aW9uX2lkIjoiMHgxMjM0In0=
        - name: start_time
          in: query
          required: false
          description: Filter markets from this Unix timestamp in seconds (inclusive)
          schema:
            type: integer
            example: 1640995200
        - name: end_time
          in: query
          required: false
          description: Filter markets until this Unix timestamp in seconds (inclusive)
          schema:
            type: integer
            example: 1672531200
      responses:
        '200':
          description: Markets response with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  markets:
                    type: array
                    items:
                      type: object
                      properties:
                        market_slug:
                          type: string
                          example: btc-updown-15m-1762516800
                        event_slug:
                          type: string
                          nullable: true
                          description: The event slug this market belongs to, or null if not associated with an event
                          example: presidential-election-winner-2028
                        condition_id:
                          type: string
                          example: '0x6876ac2b6174778c973c118aac287c49057c4d5360f896729209fe985a2c07fb'
                        title:
                          type: string
                          example: Bitcoin Up or Down - November 7, 7:00AM-7:15AM ET
                        start_time:
                          type: integer
                          description: Unix timestamp in seconds when the market starts
                          example: 1762506140
                        end_time:
                          type: integer
                          description: Unix timestamp in seconds when the market ends
                          example: 1762517700
                        completed_time:
                          type: integer
                          nullable: true
                          description: Unix timestamp in seconds when the market was completed
                          example: null
                        close_time:
                          type: integer
                          nullable: true
                          description: Unix timestamp in seconds when the market was closed
                          example: null
                        game_start_time:
                          type: string
                          format: date-time
                          nullable: true
                          description: >-
                            Datetime string in UTC format (YYYY-MM-DD HH:MM:SS.000) for when the game/event starts. Only
                            present for sports markets that have a game start time.
                          example: '2025-08-16 20:00:00.000'
                        tags:
                          type: array
                          items:
                            type: string
                          example:
                            - Up or Down
                            - Crypto Prices
                            - Hide From New
                            - Recurring
                            - Crypto
                            - Bitcoin
                            - 15M
                        volume_1_week:
                          type: number
                          description: Trading volume in USD for the past week
                          example: 0
                        volume_1_month:
                          type: number
                          description: Trading volume in USD for the past month
                          example: 0
                        volume_1_year:
                          type: number
                          description: Trading volume in USD for the past year
                          example: 0
                        volume_total:
                          type: number
                          description: Total trading volume in USD
                          example: 93.148228
                        resolution_source:
                          type: string
                          description: URL to the data source used for market resolution
                          example: https://data.chain.link/streams/btc-usd
                        image:
                          type: string
                          description: URL to the market image
                          example: https://polymarket-upload.s3.us-east-2.amazonaws.com/BTC+fullsize.png
                        description:
                          type: string
                          nullable: true
                          description: Detailed description of the market, or null if no description is available
                          example: >-
                            This market resolves to "Yes" if Bitcoin's price increases from the start to the end of the
                            15-minute window, and "No" otherwise.
                        negative_risk_id:
                          type: string
                          nullable: true
                          description: Negative risk identifier for the market, or null if not applicable
                          example: null
                        side_a:
                          type: object
                          description: First side/outcome of the market
                          properties:
                            id:
                              type: string
                              description: Token ID for side A
                              example: '14557944883400223565643640243919774851380876937588843424705199812983475639104'
                            label:
                              type: string
                              description: Label for side A
                              example: Up
                        side_b:
                          type: object
                          description: Second side/outcome of the market
                          properties:
                            id:
                              type: string
                              description: Token ID for side B
                              example: '57567439101367774829602299916701968079591032322820664013819223989961583069589'
                            label:
                              type: string
                              description: Label for side B
                              example: Down
                        winning_side:
                          type: string
                          nullable: true
                          description: The winning side of the market (null if not yet resolved)
                          example: null
                        status:
                          type: string
                          enum:
                            - open
                            - closed
                          example: open
                        extra_fields:
                          type: object
                          description: >-
                            Additional market-specific fields as a map of key-value pairs. For updown markets (markets
                            with slugs containing '-updown-15m-', '-up-or-down-', or '-updown-4h-'), this object
                            includes 'price_to_beat' and 'final_price' fields. Empty object if no extra fields are
                            present.
                          additionalProperties:
                            nullable: true
                            anyOf:
                              - type: number
                              - type: string
                              - type: boolean
                          example:
                            price_to_beat: 98765.43
                            final_price: 98801.21
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        description: Total number of markets matching the filters
                        example: 150
                      has_more:
                        type: boolean
                        description: Whether there are more markets available
                        example: true
                      pagination_key:
                        type: string
                        description: Cursor for next page. Only present when has_more is true and using cursor-based pagination.
                        example: eyJ2b2x1bWVfdG90YWwiOjEyMzQ1LjY3LCJjbG9zZV90aW1lIjpudWxsLCJjb25kaXRpb25faWQiOiIweDEyMzQifQ==
        '400':
          description: Bad Request - Invalid parameters or validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid search parameter
                  message:
                    type: string
                    example: search must be at least 2 characters long
              examples:
                search_too_short:
                  summary: Search query too short
                  value:
                    error: Invalid search parameter
                    message: search must be at least 2 characters long
                search_with_other_params:
                  summary: Search with other parameters
                  value:
                    error: Invalid query parameters
                    message: search parameter cannot be used with other filter parameters
                invalid_limit:
                  summary: Invalid limit
                  value:
                    error: Invalid limit parameter
                    message: limit must be a number between 1 and 100
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal Server Error
                  message:
                    type: string
                    example: Failed to fetch markets data
      tags:
        - Prediction Markets
  /apis/v1/polymarket/orderbooks:
    get:
      summary: Get Orderbook History
      description: >-
        Fetches historical orderbook snapshots for a specific asset (token ID) over a specified time range. If no
        start_time and end_time are provided, returns the latest orderbook snapshot for the market. Returns snapshots of
        the order book including bids, asks, and market metadata in order. All timestamps are in milliseconds. Orderbook
        data has history starting from October 14th, 2025. Note: When fetching the latest orderbook (without start/end
        times), the limit and pagination_key parameters are ignored.
      operationId: get_polymarket-orderbooks
      parameters:
        - name: token_id
          in: query
          required: true
          description: The token id (asset) for the Polymarket market
          schema:
            type: string
            example: '56369772478534954338683665819559528414197495274302917800610633957542171787417'
        - name: start_time
          in: query
          required: false
          description: >-
            Start time in Unix timestamp (milliseconds). Optional - if not provided along with end_time, returns the
            latest orderbook snapshot.
          schema:
            type: integer
            example: 1760470000000
        - name: end_time
          in: query
          required: false
          description: >-
            End time in Unix timestamp (milliseconds). Optional - if not provided along with start_time, returns the
            latest orderbook snapshot.
          schema:
            type: integer
            example: 1760480000000
        - name: limit
          in: query
          required: false
          description: >-
            Maximum number of snapshots to return (default: 100, max: 200). Ignored when fetching the latest orderbook
            without start_time and end_time.
          schema:
            type: integer
            default: 100
            maximum: 200
            example: 100
        - name: pagination_key
          in: query
          required: false
          description: >-
            Pagination key to get the next chunk of data. Ignored when fetching the latest orderbook without start_time
            and end_time.
          schema:
            type: string
            example: >-
              eyJhc3NldElkIjoiMTM1ODUxMjc2NDY0NTMxMDM0ODcyMjY1MTg3ODYyNjk5NjE0MDAyMjI5NzA0NzI3MzgxMTIwOTU1NDY0MDc5MTY4NDcxMTIyNzE2NjQiLCJ0aW1lc3RhbXAiOjE3NjExMDQwOTg5MTR9
      responses:
        '200':
          description: Orderbook history response
          content:
            application/json:
              schema:
                type: object
                properties:
                  snapshots:
                    type: array
                    description: Array of orderbook snapshots at different points in time
                    items:
                      type: object
                      properties:
                        asks:
                          type: array
                          description: Sell orders, ordered by price
                          items:
                            type: object
                            properties:
                              size:
                                type: string
                                example: '5000013.15'
                              price:
                                type: string
                                example: '0.999'
                        bids:
                          type: array
                          description: Buy orders, ordered by price
                          items:
                            type: object
                            properties:
                              size:
                                type: string
                                example: '438389.53'
                              price:
                                type: string
                                example: '0.001'
                        hash:
                          type: string
                          example: 85c493ebeea97e2f70c85a1469aede05f892408f
                        minOrderSize:
                          type: string
                          example: '5'
                        negRisk:
                          type: boolean
                          example: true
                        assetId:
                          type: string
                          example: '56369772478534954338683665819559528414197495274302917800610633957542171787417'
                        timestamp:
                          type: integer
                          description: Timestamp of the snapshot in milliseconds
                          example: 1760471849407
                        tickSize:
                          type: string
                          example: '0.001'
                        indexedAt:
                          type: integer
                          description: When the snapshot was indexed in milliseconds
                          example: 1760471852863
                        market:
                          type: string
                          example: '0xd10bc768ede58b53ed400594240b0a0603134a32dab89ec823a18759cbc180ca'
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        example: 100
                      count:
                        type: integer
                        description: Number of snapshots returned
                        example: 4
                      pagination_key:
                        type: string
                        description: The pagination key to pass in to get the next chunk of data
                        example: >-
                          eyJhc3NldElkIjoiMTM1ODUxMjc2NDY0NTMxMDM0ODcyMjY1MTg3ODYyNjk5NjE0MDAyMjI5NzA0NzI3MzgxMTIwOTU1NDY0MDc5MTY4NDcxMTIyNzE2NjQiLCJ0aW1lc3RhbXAiOjE3NjExMDQwOTg5MTR9
                      has_more:
                        type: boolean
                        description: Whether there are more snapshots available
                        example: false
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid parameters
                  message:
                    type: string
                    example: assetId, start_time, and end_time are required
      tags:
        - Prediction Markets
  /apis/v1/polymarket/orders:
    get:
      summary: Get Orders
      description: >-
        Fetches order data with optional filtering by market, condition, token, time range, and user. Returns orders
        that match either primary or secondary token IDs for markets. If no filters provided, fetches the latest trades
        happening in real-time. Only one of market_slug, token_id, or condition_id can be provided.
      operationId: get_polymarket-orders
      parameters:
        - name: market_slug
          in: query
          required: false
          description: Filter orders by market slug
          schema:
            type: string
            example: bitcoin-up-or-down-july-25-8pm-et
        - name: condition_id
          in: query
          required: false
          description: Filter orders by condition ID
          schema:
            type: string
            example: '0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57'
        - name: token_id
          in: query
          required: false
          description: Filter orders by token ID
          schema:
            type: string
            example: '58519484510520807142687824915233722607092670035910114837910294451210534222702'
        - name: start_time
          in: query
          required: false
          description: Filter orders from this Unix timestamp in seconds (inclusive)
          schema:
            type: integer
            example: 1640995200
        - name: end_time
          in: query
          required: false
          description: Filter orders until this Unix timestamp in seconds (inclusive)
          schema:
            type: integer
            example: 1672531200
        - name: limit
          in: query
          required: false
          description: Number of orders to return (1-1000)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
            example: 50
        - name: pagination_key
          in: query
          required: false
          description: Base64-encoded cursor for efficient pagination. Returned in the previous response's pagination object.
          schema:
            type: string
            example: >-
              eyJibG9ja190aW1lc3RhbXAiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJ0eF9oYXNoIjoiMHgxMjM0NTY3ODkwYWJjZGVmIiwibG9nX2luZGV4IjoxMCwidG90YWwiOjUxMDk2MTl9
        - name: user
          in: query
          required: false
          description: Filter orders by user (wallet address)
          schema:
            type: string
            example: '0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b'
      responses:
        '200':
          description: Orders response with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      type: object
                      properties:
                        token_id:
                          type: string
                          example: '58519484510520807142687824915233722607092670035910114837910294451210534222702'
                        token_label:
                          type: string
                          description: Human readable label for this outcome (yes/no etc)
                          example: 'Yes'
                        side:
                          type: string
                          enum:
                            - BUY
                            - SELL
                          example: BUY
                        market_slug:
                          type: string
                          example: bitcoin-up-or-down-july-25-8pm-et
                        condition_id:
                          type: string
                          example: '0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57'
                        shares:
                          type: number
                          description: Raw number of shares purchased (from the blockchain)
                          example: 4995000
                        shares_normalized:
                          type: number
                          description: Number of shares purchased normalized (this is raw divided by 1000000)
                          example: 4.995
                        price:
                          type: number
                          description: Price per share
                          example: 0.65
                        block_number:
                          type: integer
                          description: Block number where the order was placed
                          example: 123456789
                        log_index:
                          type: integer
                          description: Log index of the order event in the block
                          example: 42
                        tx_hash:
                          type: string
                          description: Transaction hash of the order
                          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12'
                        title:
                          type: string
                          description: Market title
                          example: Will Bitcoin be above $50,000 on July 25, 2025 at 8:00 PM ET?
                        timestamp:
                          type: integer
                          description: Unix timestamp in seconds when the order was placed
                          example: 1757008834
                        order_hash:
                          type: string
                          description: Hash of the order
                          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
                        user:
                          type: string
                          description: Maker address of the order
                          example: '0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b'
                        taker:
                          type: string
                          description: >-
                            Taker address that was part of this trade. Note: This can often be the CTF exchange and is
                            not always the true taker, proceed with caution using taker information
                          example: '0x8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e'
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        example: 50
                      offset:
                        type: integer
                        example: 0
                      total:
                        type: integer
                        description: Total number of orders matching the filters
                        example: 1250
                      has_more:
                        type: boolean
                        description: Whether there are more orders available
                        example: true
                      pagination_key:
                        type: string
                        description: >-
                          Base64-encoded cursor for the next page. Only present when there are more results. Use this in
                          the next request instead of offset.
                        example: >-
                          eyJibG9ja190aW1lc3RhbXAiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJ0eF9oYXNoIjoiMHgxMjM0NTY3ODkwYWJjZGVmIiwibG9nX2luZGV4IjoxMCwidG90YWwiOjUxMDk2MTl9
        '400':
          description: Bad Request - Invalid parameters or validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid start_time parameter
                  message:
                    type: string
                    example: start_time must be a valid Unix timestamp
              examples:
                invalid_timestamp:
                  summary: Invalid timestamp
                  value:
                    error: Invalid start_time parameter
                    message: start_time must be a valid Unix timestamp
                invalid_time_range:
                  summary: Invalid time range
                  value:
                    error: Invalid time range
                    message: start_time must be less than end_time
                invalid_limit:
                  summary: Invalid limit
                  value:
                    error: Invalid limit parameter
                    message: limit must be a number between 1 and 1000
                missing_required_filter:
                  summary: Missing required filter
                  value:
                    error: Missing required filter parameter
                    message: At least one of market_slug, condition_id, user, or token_id must be provided
                invalid_filter_combination:
                  summary: Invalid filter combination
                  value:
                    error: Invalid filter combination
                    message: Only one of market_slug, token_id, or condition_id can be provided
                invalid_pagination_key:
                  summary: Invalid pagination key
                  value:
                    error: Invalid pagination key
                    message: pagination_key is invalid or corrupted
        '401':
          description: Unauthorized - Offset deprecated for large values
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Offset deprecated
                  message:
                    type: string
                    example: >-
                      Offsets greater than 10,000 are no longer supported. Please use pagination_key for efficient
                      pagination.
                  docs:
                    type: string
                    example: https://aisa.one/docs/api-reference/prediction-market/get_polymarket-events
      tags:
        - Prediction Markets
  /apis/v1/polymarket/positions/wallet/{wallet_address}:
    parameters:
      - name: wallet_address
        in: path
        required: true
        description: The Proxy wallet address to fetch positions for
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x1234567890abcdef1234567890abcdef12345678'
    get:
      summary: Get Positions
      description: >-
        Fetches all Polymarket positions for a proxy wallet address. Returns positions with balance >= 10,000 shares
        (0.01 normalized) with market info.
      operationId: get_polymarket-positions
      parameters:
        - name: limit
          in: query
          required: false
          description: Maximum number of positions to return per page. Defaults to 100, maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: pagination_key
          in: query
          required: false
          description: Pagination key returned from previous request to fetch next page of results
          schema:
            type: string
            example: NjhlMGM4MDAtZDkwNi00YjMyLWEzOWMtYTRlMTk5MzRkNWVl
      responses:
        '200':
          description: Positions response
          content:
            application/json:
              schema:
                type: object
                properties:
                  wallet_address:
                    type: string
                    description: The wallet address (normalized to lowercase)
                    example: '0x1234567890abcdef1234567890abcdef12345678'
                  positions:
                    type: array
                    description: Array of position objects
                    items:
                      type: object
                      properties:
                        wallet:
                          type: string
                          description: The wallet address
                          example: '0x1234567890abcdef1234567890abcdef12345678'
                        token_id:
                          type: string
                          description: The Polymarket token ID for this position
                          example: '19701256321759583954581192053894521654935987478209343000964756587964612528044'
                        condition_id:
                          type: string
                          description: The condition ID for the market
                          example: 0x1234abcd...
                        title:
                          type: string
                          description: Market title
                          example: Will Bitcoin reach $100k by end of 2025?
                        shares:
                          type: integer
                          description: Number of shares (raw, not normalized)
                          example: 50000000
                        shares_normalized:
                          type: number
                          description: Number of shares normalized (divided by 1,000,000)
                          example: 50
                        redeemable:
                          type: boolean
                          description: Whether this position can be redeemed (market completed and is closed)
                          example: false
                        market_slug:
                          type: string
                          description: The market slug
                          example: will-bitcoin-reach-100k-by-end-of-2025
                        event_slug:
                          type: string
                          description: The event slug
                          example: bitcoin-price-predictions
                        image:
                          type: string
                          description: URL to market image
                          example: https://polymarket.com/images/...
                        label:
                          type: string
                          description: The outcome label for this token (e.g., 'Yes' or 'No')
                          example: 'Yes'
                        winning_outcome:
                          type: object
                          nullable: true
                          description: >-
                            Information about the winning outcome if market is closed, null if market is still open or
                            no outcome determined
                          properties:
                            id:
                              type: string
                              description: Token ID of the winning outcome
                              example: '19701256321759583954581192053894521654935987478209343000964756587964612528044'
                            label:
                              type: string
                              description: Label of the winning outcome
                              example: 'Yes'
                        start_time:
                          type: integer
                          description: Market start timestamp (Unix seconds)
                          example: 1640995200
                        end_time:
                          type: integer
                          description: Market end timestamp (Unix seconds)
                          example: 1672531200
                        completed_time:
                          type: integer
                          nullable: true
                          description: Market completion timestamp (Unix seconds), currently always null
                          example: null
                        close_time:
                          type: integer
                          nullable: true
                          description: Market close timestamp (Unix seconds) if market is closed, null if still open
                          example: 1672531200
                        game_start_time:
                          type: string
                          nullable: true
                          description: Game start time for sports markets, null for non-sports markets
                          example: '2025-01-15T19:00:00Z'
                        market_status:
                          type: string
                          enum:
                            - open
                            - closed
                          description: Whether the market is open or closed
                          example: open
                        negativeRisk:
                          type: boolean
                          description: Whether this market has negative risk
                          example: false
                      required:
                        - wallet
                        - token_id
                        - condition_id
                        - title
                        - shares
                        - shares_normalized
                        - redeemable
                        - market_slug
                        - event_slug
                        - image
                        - label
                        - winning_outcome
                        - start_time
                        - end_time
                        - completed_time
                        - close_time
                        - game_start_time
                        - market_status
                        - negativeRisk
                  pagination:
                    type: object
                    description: Pagination information
                    properties:
                      has_more:
                        type: boolean
                        description: Whether there are more results available
                        example: false
                      limit:
                        type: integer
                        description: The limit used for this request
                        example: 100
                      pagination_key:
                        type: string
                        nullable: true
                        description: Pagination key to use for fetching next page, null if no more pages
                        example: null
                    required:
                      - has_more
                      - limit
                      - pagination_key
                required:
                  - wallet_address
                  - positions
                  - pagination
              examples:
                with_positions:
                  summary: Wallet with positions
                  description: Response when wallet has active positions
                  value:
                    wallet_address: '0x1234567890abcdef1234567890abcdef12345678'
                    positions:
                      - wallet: '0x1234567890abcdef1234567890abcdef12345678'
                        token_id: '19701256321759583954581192053894521654935987478209343000964756587964612528044'
                        condition_id: 0xabcd1234...
                        title: Will Bitcoin reach $100k by end of 2025?
                        shares: 50000000
                        shares_normalized: 50
                        redeemable: false
                        market_slug: will-bitcoin-reach-100k-by-end-of-2025
                        event_slug: bitcoin-price-predictions
                        image: https://polymarket.com/images/...
                        label: 'Yes'
                        winning_outcome: null
                        start_time: 1640995200
                        end_time: 1672531200
                        completed_time: null
                        close_time: null
                        game_start_time: null
                        market_status: open
                        negativeRisk: false
                    pagination:
                      has_more: false
                      limit: 100
                      pagination_key: null
                empty_positions:
                  summary: Wallet with no positions
                  description: Response when wallet has no positions >= 10,000 shares
                  value:
                    wallet_address: '0x1234567890abcdef1234567890abcdef12345678'
                    positions: []
                    pagination:
                      has_more: false
                      limit: 100
                      pagination_key: null
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid wallet address
                  message:
                    type: string
                    example: wallet_address must be a valid Ethereum address (0x followed by 40 hex characters)
              examples:
                missing_wallet:
                  summary: Missing wallet address
                  value:
                    error: Missing parameter
                    message: wallet_address is required
                invalid_wallet:
                  summary: Invalid wallet address format
                  value:
                    error: Invalid wallet address
                    message: wallet_address must be a valid Ethereum address (0x followed by 40 hex characters)
                invalid_limit:
                  summary: Invalid limit parameter
                  value:
                    error: Invalid limit parameter
                    message: limit must be a number between 1 and 100
      tags:
        - Prediction Markets
  /apis/v1/polymarket/wallet:
    get:
      summary: Get Wallet
      description: >-
        Fetches wallet information by providing either an EOA (Externally Owned Account) address, a proxy wallet
        address, or a user handle. Returns the associated EOA, proxy, wallet type, handle, pseudonym, and profile image.
        Optionally returns trading metrics when `with_metrics=true`.
      operationId: get_polymarket-wallet
      parameters:
        - name: eoa
          in: query
          required: false
          description: >-
            EOA (Externally Owned Account) wallet address. Either `eoa`, `proxy`, or `handle` must be provided, but not
            more than one.
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
            example: '0xe9a69b28ffd86f6ea0c5d8171c95537479b84a29'
        - name: proxy
          in: query
          required: false
          description: Proxy wallet address. Either `eoa`, `proxy`, or `handle` must be provided, but not more than one.
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
            example: '0x60881d7dce725bfb0399ee0b11cc11f5782f257d'
        - name: handle
          in: query
          required: false
          description: >-
            User handle/username. Accepts both formats: `username` or `@username` (the @ prefix will be automatically
            stripped). Either `eoa`, `proxy`, or `handle` must be provided, but not more than one.
          schema:
            type: string
            example: satoshi
        - name: with_metrics
          in: query
          required: false
          description: >-
            Whether to include wallet trading metrics (total volume, trades, and markets). Pass `true` to include
            metrics. Metrics are computed only when explicitly requested for performance reasons.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            example: 'true'
        - name: start_time
          in: query
          required: false
          description: Optional start date for metrics calculation (Unix timestamp in seconds). Only used when `with_metrics=true`.
          schema:
            type: integer
            example: 1640995200
        - name: end_time
          in: query
          required: false
          description: Optional end date for metrics calculation (Unix timestamp in seconds). Only used when `with_metrics=true`.
          schema:
            type: integer
            example: 1672531200
      responses:
        '200':
          description: Wallet information response
          content:
            application/json:
              schema:
                type: object
                properties:
                  eoa:
                    type: string
                    description: The EOA (Externally Owned Account) wallet address
                    example: '0xe9a69b28ffd86f6ea0c5d8171c95537479b84a29'
                  proxy:
                    type: string
                    description: The proxy wallet address
                    example: '0x60881d7dce725bfb0399ee0b11cc11f5782f257d'
                  wallet_type:
                    type: string
                    description: The type of wallet
                    example: safe
                  handle:
                    type: string
                    nullable: true
                    description: User handle/username
                    example: satoshi
                  pseudonym:
                    type: string
                    nullable: true
                    description: User pseudonym/display name
                    example: Satoshi Nakamoto
                  image:
                    type: string
                    nullable: true
                    description: User profile image URL
                    example: https://example.com/avatar.png
                  wallet_metrics:
                    type: object
                    description: Trading metrics for this wallet (only present when with_metrics=true)
                    properties:
                      total_volume:
                        type: number
                        description: Total trading volume in USD
                        example: 150000.5
                      total_trades:
                        type: number
                        description: Total number of trades (orders where this wallet was the maker)
                        example: 450
                      total_markets:
                        type: number
                        description: Total number of unique markets traded in
                        example: 25
                      highest_volume_day:
                        type: object
                        description: The day with the highest number of shares traded
                        properties:
                          date:
                            type: string
                            format: date
                            description: Date in YYYY-MM-DD format
                            example: '2025-10-12'
                          volume:
                            type: number
                            description: Total shares traded on that day (normalized, divided by 1,000,000)
                            example: 25000.75
                          trades:
                            type: number
                            description: Number of trades executed on that day
                            example: 145
                        required:
                          - date
                          - volume
                          - trades
                      merges:
                        type: number
                        description: Total number of token merges performed by this wallet
                        example: 262
                      splits:
                        type: number
                        description: Total number of token splits performed by this wallet
                        example: 31
                      conversions:
                        type: number
                        description: Total number of token conversions performed by this wallet
                        example: 4
                      redemptions:
                        type: number
                        description: Total number of token redemptions performed by this wallet
                        example: 2338
                required:
                  - eoa
                  - proxy
                  - wallet_type
              examples:
                without_metrics:
                  summary: Basic wallet information
                  description: Response when with_metrics is not provided or false
                  value:
                    eoa: '0xe9a69b28ffd86f6ea0c5d8171c95537479b84a29'
                    proxy: '0x60881d7dce725bfb0399ee0b11cc11f5782f257d'
                    wallet_type: safe
                    handle: satoshi
                    pseudonym: Satoshi Nakamoto
                    image: https://example.com/avatar.png
                with_metrics:
                  summary: Wallet information with metrics
                  description: Response when with_metrics=true
                  value:
                    eoa: '0xe9a69b28ffd86f6ea0c5d8171c95537479b84a29'
                    proxy: '0x60881d7dce725bfb0399ee0b11cc11f5782f257d'
                    wallet_type: safe
                    handle: satoshi
                    pseudonym: Satoshi Nakamoto
                    image: https://example.com/avatar.png
                    wallet_metrics:
                      total_volume: 150000.5
                      total_trades: 450
                      total_markets: 25
                      highest_volume_day:
                        date: '2025-10-12'
                        volume: 25000.75
                        trades: 145
        '400':
          description: Bad Request - Invalid or missing parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: BAD_REQUEST
                  message:
                    type: string
                    example: Either eoa or proxy parameter must be provided, but not both
              examples:
                missing_parameter:
                  summary: Missing required parameter
                  value:
                    error: BAD_REQUEST
                    message: Either eoa, proxy, or handle parameter must be provided
                both_parameters:
                  summary: Both parameters provided
                  value:
                    error: BAD_REQUEST
                    message: Only one of eoa, proxy, or handle can be provided
                invalid_address:
                  summary: Invalid wallet address format
                  value:
                    error: BAD_REQUEST
                    message: Invalid wallet address format
        '404':
          description: Not Found - Wallet not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: NOT_FOUND
                  message:
                    type: string
                    example: Wallet not found
      tags:
        - Prediction Markets
  /apis/v1/polymarket/wallet/pnl:
    parameters:
      - name: wallet_address
        in: path
        required: true
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x1234567890abcdef1234567890abcdef12345678'
    get:
      summary: Get Wallet PnL
      description: >-
        Fetches the REALIZED profit and loss (PnL) for a specific wallet address over a specified time range and
        granularity. **Note:** This will differ to what you see on Polymarket's dashboard since Polymarket showcases
        historical unrealized PnL. This API tracks realized gains only - from either confirmed sells or redeems. We do
        not realize a gain/loss until a finished market is redeemed.
      operationId: get_polymarket-wallet-pnl
      parameters:
        - name: wallet_address
          in: query
          required: true
          description: Polymarket wallet address (0x-prefixed).
          schema:
            type: string
          example: '0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b'
        - name: granularity
          in: query
          required: true
          schema:
            type: string
            enum:
              - day
              - week
              - month
              - year
              - all
            example: day
        - name: start_time
          in: query
          required: false
          description: Defaults to first day of first trade if not provided.
          schema:
            type: integer
            example: 1726857600
        - name: end_time
          in: query
          required: false
          description: Defaults to the current date if not provided.
          schema:
            type: integer
            example: 1758316829
      responses:
        '200':
          description: PnL response
          content:
            application/json:
              schema:
                type: object
                properties:
                  granularity:
                    type: string
                    example: day
                  start_time:
                    type: integer
                    example: 1726857600
                  end_time:
                    type: integer
                    example: 1758316829
                  wallet_address:
                    type: string
                    example: '0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b'
                  pnl_over_time:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: integer
                          example: 1726857600
                        pnl_to_date:
                          type: number
                          example: 2001
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: BAD_REQUEST
                  message:
                    type: string
                    example: Invalid or missing parameters.
        '503':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  message:
                    type: string
                    example: Internal Server Error. Dome Admins contacted.
      tags:
        - Prediction Markets
  /apis/v1/polymarket/wallet/pnl/{wallet_address}:
    get:
      summary: Realized PnL over time for a wallet (cumulative series)
      description: Auto-generated stub from Prediction Market Data skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getPolymarketWalletPnlWalletAddress
      tags:
        - Prediction Markets
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/prices:
    get:
      tags:
        - Market Data
      operationId: getPrices
      summary: Get historical stock price data
      description: Get end-of-day (EOD) historical price data for stocks.
      parameters:
        - name: ticker
          in: query
          description: The stock ticker symbol (e.g. AAPL, MSFT).
          required: true
          schema:
            type: string
        - name: interval
          in: query
          description: The time interval for the price data.
          required: true
          schema:
            type: string
            enum:
              - day
              - week
              - month
              - year
        - name: start_date
          in: query
          description: 'The start date for the price data (format: YYYY-MM-DD).'
          required: true
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          description: 'The end date for the price data (format: YYYY-MM-DD).'
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Price data response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/prices/snapshot:
    get:
      tags:
        - Market Data
      operationId: getPriceSnapshot
      summary: Price Snapshot (Real-Time)
      description: Get the real-time price snapshot for a stock, including the current price, day change, and day change percent.
      parameters:
        - name: ticker
          in: query
          description: The stock ticker symbol (e.g. AAPL, MSFT).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Price snapshot response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceSnapshotResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /apis/v1/scholar/explain:
    get:
      summary: Generate result explanations
      description: Auto-generated stub from Multi-source Search skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getScholarExplain
      tags:
        - Scholar Search
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/scholar/search/explain:
    post:
      summary: Explain search results
      description: Generate explanations for search results in different languages and formats
      operationId: explainSearch
      tags:
        - Search
        - Explanation
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExplainSearchRequest'
      responses:
        '200':
          description: Successful explanation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplainSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /apis/v1/scholar/search/mixed:
    post:
      summary: Smart search combining web and academic results
      description: Perform intelligent search that combines web and academic results
      operationId: searchSmart
      tags:
        - Search
        - Smart
      security:
        - BearerAuth: []
      parameters:
        - name: query
          in: query
          required: true
          description: Search query for scholarly materials
          schema:
            type: string
            example: machine learning
        - name: max_num_results
          in: query
          description: Maximum number of search results to return, up to 100
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: as_ylo
          in: query
          description: Year of publication lower bound
          schema:
            type: integer
            nullable: true
            minimum: 1900
            maximum: 2030
        - name: as_yhi
          in: query
          description: Year of publication upper bound
          schema:
            type: integer
            nullable: true
            minimum: 1900
            maximum: 2030
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                query:
                  type: string
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmartSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /apis/v1/scholar/search/scholar:
    post:
      summary: Search academic papers
      description: Perform academic paper search using Google Scholar or similar sources
      operationId: searchScholar
      tags:
        - Search
        - Academic
      security:
        - BearerAuth: []
      parameters:
        - name: query
          in: query
          required: true
          description: Search query for scholarly materials
          schema:
            type: string
            example: machine learning
        - name: max_num_results
          in: query
          description: Maximum number of search results to return, up to 100
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: as_ylo
          in: query
          description: Year of publication lower bound
          schema:
            type: integer
            nullable: true
            minimum: 1900
            maximum: 2030
        - name: as_yhi
          in: query
          description: Year of publication upper bound
          schema:
            type: integer
            nullable: true
            minimum: 1900
            maximum: 2030
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                query:
                  type: string
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScholarSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /apis/v1/scholar/search/smart:
    get:
      summary: Hybrid scholar search
      description: Auto-generated stub from Multi-source Search skill. Detailed documentation pending in AIsa-team/docs repo.
      operationId: getScholarSearchSmart
      tags:
        - Scholar Search
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid API key
  /apis/v1/scholar/search/web:
    post:
      summary: Search the web
      description: Perform web search and return structured results
      operationId: searchWeb
      tags:
        - Search
        - Web
      security:
        - BearerAuth: []
      parameters:
        - name: query
          in: query
          required: true
          description: Search query for scholarly materials
          schema:
            type: string
            example: machine learning
        - name: max_num_results
          in: query
          description: Maximum number of search results to return, up to 100
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: as_ylo
          in: query
          description: Year of publication lower bound
          schema:
            type: integer
            nullable: true
            minimum: 1900
            maximum: 2030
        - name: as_yhi
          in: query
          description: Year of publication upper bound
          schema:
            type: integer
            nullable: true
            minimum: 1900
            maximum: 2030
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                query:
                  type: string
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /apis/v1/services/aigc/tasks/{task_id}:
    get:
      summary: Get video generation task result
      description: >-
        Poll the status and result of a task created by `POST /apis/v1/services/aigc/video-generation/video-synthesis`.
        The `task_id` is a **path parameter**, not a query string.


        Suggested polling: every 3–5 seconds, with a hard timeout around 5 minutes.
      operationId: getVideoSynthesisTask
      tags:
        - Video Generation
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 'Task ID returned by the video-synthesis create call. Unknown IDs return `task_status: "UNKNOWN"` (HTTP 200).'
      responses:
        '200':
          description: Task status response. Always HTTP 200 — inspect `output.task_status` to tell lifecycle states apart.
          content:
            application/json:
              schema:
                type: object
                properties:
                  output:
                    type: object
                    properties:
                      task_id:
                        type: string
                      task_status:
                        type: string
                        enum:
                          - PENDING
                          - RUNNING
                          - SUCCEEDED
                          - FAILED
                          - CANCELED
                          - UNKNOWN
                      video_url:
                        type: string
                        format: uri
                        description: Present on `SUCCEEDED`. Short-lived URL — download and persist the video before it expires.
                      orig_prompt:
                        type: string
                        description: The original prompt as stored by the upstream provider.
                      submit_time:
                        type: string
                        description: When the task was accepted.
                      scheduled_time:
                        type: string
                        description: When the task was scheduled for execution.
                      end_time:
                        type: string
                        description: When the task reached a terminal state.
                      code:
                        type: string
                        description: 'Present on `FAILED`. Example: `InvalidParameter`.'
                      message:
                        type: string
                        description: Present on `FAILED`. Human-readable failure reason.
                  usage:
                    type: object
                    description: Present on `SUCCEEDED`.
                    properties:
                      input_video_duration:
                        type: integer
                        description: Duration of any input video reference (0 when none).
                      output_video_duration:
                        type: integer
                        description: Duration of the generated video in seconds.
                      duration:
                        type: number
                        description: Total duration used for billing.
                      video_count:
                        type: integer
                        description: Number of videos produced (always 1 today).
                      size:
                        type: string
                        description: >-
                          Actual dimensions of the generated video, formatted as `WIDTH*HEIGHT` (e.g., `1920*1080`).
                          Note the `*` separator. Present on `wan2.6-*` outputs.
                        example: 1920*1080
                      ratio:
                        type: string
                        description: Aspect ratio of the output (e.g., `16:9`). Present on `wan2.7-t2v` outputs.
                        example: '16:9'
                      SR:
                        type: integer
                        description: >-
                          Super-resolution output height. `wan2.6-t2v` upscales 720P input to 1080. `wan2.6-i2v`,
                          `wan2.7-t2v`, `wan2.7-i2v` return 720.
                        example: 1080
                  request_id:
                    type: string
              examples:
                succeeded:
                  summary: SUCCEEDED — video_url is populated
                  value:
                    output:
                      task_id: b3be072e-cc82-4033-8fb7-0b089846544f
                      task_status: SUCCEEDED
                      video_url: https://cdn.aisa.one/videos/wan2.6/20260418-abc.mp4
                      orig_prompt: cinematic close-up, slow push-in, shallow depth of field
                      submit_time: '2026-04-18 15:16:01.841'
                      scheduled_time: '2026-04-18 15:16:01.867'
                      end_time: '2026-04-18 15:16:42.512'
                    usage:
                      output_video_duration: 5
                      video_count: 1
                      SR: 720
                    request_id: 8a931b13-c44f-9230-a76b-83487d840060
                failed:
                  summary: FAILED (invalid prompt — not billed)
                  value:
                    output:
                      task_id: b3be072e-cc82-4033-8fb7-0b089846544f
                      task_status: FAILED
                      code: InvalidParameter
                      message: prompt must contain words
                      submit_time: '2026-04-18 15:16:01.841'
                      scheduled_time: '2026-04-18 15:16:01.867'
                      end_time: '2026-04-18 15:16:01.941'
                    request_id: 8a931b13-c44f-9230-a76b-83487d840060
                running:
                  summary: RUNNING (still processing)
                  value:
                    output:
                      task_id: b3be072e-cc82-4033-8fb7-0b089846544f
                      task_status: RUNNING
                    request_id: 8a931b13-c44f-9230-a76b-83487d840060
                unknown:
                  summary: UNKNOWN task_id (still returns HTTP 200)
                  value:
                    output:
                      task_id: bogus-task-id
                      task_status: UNKNOWN
                    request_id: 71b2b0ad-cb6f-9de4-a8bc-a88e4fb72f0e
        '401':
          description: Missing or invalid AIsa API key.
        '500':
          description: >-
            `unsupported uri` — check the path. The correct pattern is `/services/aigc/tasks/{task_id}`, not
            `/services/aigc/tasks?task_id=`.
  /apis/v1/services/aigc/video-generation/video-synthesis:
    post:
      summary: Create a video generation task
      description: >-
        Submit an asynchronous video generation task. Returns a `task_id` you then poll via `GET
        /apis/v1/services/aigc/tasks/{task_id}`.


        **Models.** Four Wan variants are accepted on this single endpoint:


        | Model | Kind | Image input field |

        | --- | --- | --- |

        | `wan2.6-t2v` | text-to-video | _n/a_ |

        | `wan2.6-i2v` | image-to-video | `input.img_url` |

        | `wan2.7-t2v` | text-to-video | _n/a_ |

        | `wan2.7-i2v` | image-to-video | `input.media` ⚠️ *not* `input.img_url` |


        **Header.** `X-DashScope-Async: enable` is required.


        **Body.** `model` and `input.prompt` are always required. For i2v, provide a reference image using the field
        indicated in the table above — `wan2.6-i2v` uses `input.img_url` (string URL), while `wan2.7-i2v` uses
        `input.media` (array of URLs).


        Failed tasks (e.g., invalid prompt, missing required field) are **not billed** — the task-status response
        returns `task_status: "FAILED"` with a `code` and `message`.
      operationId: createVideoSynthesisTask
      tags:
        - Video Generation
      parameters:
        - name: X-DashScope-Async
          in: header
          required: true
          schema:
            type: string
            enum:
              - enable
          description: Must be `enable` to run asynchronously (the only mode currently supported).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  enum:
                    - wan2.6-t2v
                    - wan2.6-i2v
                    - wan2.7-t2v
                    - wan2.7-i2v
                  description: >-
                    Video generation model. Use `-t2v` suffix for text-to-video, `-i2v` for image-to-video. **Note the
                    i2v schema difference:** `wan2.6-i2v` takes a reference image via `input.img_url` (string), while
                    `wan2.7-i2v` takes it via `input.media` (array).
                  example: wan2.6-t2v
                input:
                  type: object
                  required:
                    - prompt
                  description: >-
                    Required body container. `prompt` is always required; image inputs depend on the model (see field
                    descriptions).
                  properties:
                    prompt:
                      type: string
                      description: >-
                        Text prompt describing the video. Must contain words — empty or whitespace-only prompts fail
                        upstream with `prompt must contain words`.
                    negative_prompt:
                      type: string
                      description: Optional negative prompt.
                    img_url:
                      type: string
                      format: uri
                      description: >-
                        Reference image URL. **Required** for `wan2.6-i2v`. Ignored by t2v models. **Do NOT use for
                        `wan2.7-i2v`** — that model uses `media` instead.
                    media:
                      type: array
                      items:
                        type: string
                        format: uri
                      description: >-
                        Reference image URLs as an array. **Required** for `wan2.7-i2v`. Do NOT use `img_url` with
                        `wan2.7-i2v` — the upstream validator rejects submissions without `input.media`.
                    audio_url:
                      type: string
                      format: uri
                      description: Optional reference audio URL.
                parameters:
                  type: object
                  properties:
                    resolution:
                      type: string
                      enum:
                        - 720P
                        - 1080P
                      default: 720P
                    duration:
                      type: integer
                      enum:
                        - 5
                        - 10
                      default: 5
                      description: Video length in seconds.
                    shot_type:
                      type: string
                      enum:
                        - single
                        - multi
                      default: single
                    watermark:
                      type: boolean
                      default: false
                    seed:
                      type: integer
                      minimum: 0
                      maximum: 2147483647
            examples:
              wan26_t2v:
                summary: wan2.6-t2v — text-to-video, 5 s, 720P
                value:
                  model: wan2.6-t2v
                  input:
                    prompt: cinematic close-up, slow push-in, shallow depth of field
                  parameters:
                    resolution: 720P
                    duration: 5
              wan26_i2v:
                summary: wan2.6-i2v — image-to-video (uses img_url)
                value:
                  model: wan2.6-i2v
                  input:
                    prompt: gentle camera orbit, golden hour lighting
                    img_url: https://example.com/reference.jpg
                  parameters:
                    resolution: 1080P
                    duration: 10
              wan27_t2v:
                summary: wan2.7-t2v — text-to-video, newer model
                value:
                  model: wan2.7-t2v
                  input:
                    prompt: wide sweeping shot of a neon cyberpunk skyline at dusk
                  parameters:
                    resolution: 720P
                    duration: 5
              wan27_i2v:
                summary: wan2.7-i2v — image-to-video (uses media ARRAY, not img_url)
                value:
                  model: wan2.7-i2v
                  input:
                    prompt: gentle zoom with parallax, cinematic color grading
                    media:
                      - https://example.com/reference.jpg
                  parameters:
                    resolution: 720P
                    duration: 5
      responses:
        '200':
          description: Task created — poll `/services/aigc/tasks/{task_id}` for progress.
          content:
            application/json:
              schema:
                type: object
                properties:
                  output:
                    type: object
                    properties:
                      task_id:
                        type: string
                        description: Pass this to `GET /services/aigc/tasks/{task_id}`.
                      task_status:
                        type: string
                        enum:
                          - PENDING
                  request_id:
                    type: string
              example:
                output:
                  task_id: b3be072e-cc82-4033-8fb7-0b089846544f
                  task_status: PENDING
                request_id: 8a931b13-c44f-9230-a76b-83487d840060
        '400':
          description: Invalid request body.
        '401':
          description: Missing or invalid AIsa API key.
        '429':
          description: Rate limit hit.
        '500':
          description: >-
            `model not supported` (the model isn't routed through this endpoint) or `input param is required` (body
            missing `input`).


            Note: for `wan2.7-i2v`, submission **succeeds with HTTP 200** even without the image input — the task later
            lands in `FAILED` status with `code: "InvalidParameter"` and `message: "Field required: input.media"`.
  /apis/v1/tavily/crawl:
    post:
      tags:
        - https://docs.tavily.com/documentation/api-reference/endpoint/crawl
      summary: Graph-based website traversal tool using Tavily Crawl.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The root URL to begin the crawl.
                  example: docs.tavily.com
                instructions:
                  type: string
                  description: Natural language instructions for the crawler.
                chunks_per_source:
                  type: integer
                  default: 3
                  description: Maximum number of relevant chunks returned per source.
                  minimum: 1
                  maximum: 5
                max_depth:
                  type: integer
                  default: 1
                  description: Max depth of the crawl.
                  minimum: 1
                  maximum: 5
                max_breadth:
                  type: integer
                  default: 20
                  description: Max number of links to follow per level of the tree.
                  minimum: 1
                  maximum: 500
                limit:
                  type: integer
                  default: 50
                  description: Total number of links the crawler will process before stopping.
                  minimum: 1
                select_paths:
                  type: array
                  items:
                    type: string
                  description: Regex patterns to select only URLs with specific path patterns.
                select_domains:
                  type: array
                  items:
                    type: string
                  description: Regex patterns to select crawling to specific domains or subdomains.
                exclude_paths:
                  type: array
                  items:
                    type: string
                  description: Regex patterns to exclude URLs with specific path patterns.
                exclude_domains:
                  type: array
                  items:
                    type: string
                  description: Regex patterns to exclude specific domains or subdomains from crawling.
                allow_external:
                  type: boolean
                  default: true
                  description: Include external domain links in the final results list.
                include_images:
                  type: boolean
                  default: false
                  description: Include images in the crawl results.
                extract_depth:
                  type: string
                  enum:
                    - basic
                    - advanced
                  default: basic
                  description: Depth of the extraction process.
                format:
                  type: string
                  enum:
                    - markdown
                    - text
                  default: markdown
                  description: Format of the extracted web page content.
                include_favicon:
                  type: boolean
                  default: false
                  description: Include the favicon URL for each result.
                timeout:
                  type: number
                  format: float
                  default: 150
                  description: Maximum time in seconds to wait for the crawl operation.
                  minimum: 10
                  maximum: 150
                include_usage:
                  type: boolean
                  default: false
                  description: Include credit usage information in the response.
              required:
                - url
      responses:
        '200':
          description: Crawl results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  base_url:
                    type: string
                    description: The base URL that was crawled.
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          description: URL of the crawled page.
                        raw_content:
                          type: string
                          description: Extracted raw content from the page.
                        favicon:
                          type: string
                          description: Favicon URL of the crawled page.
                  response_time:
                    type: number
                    format: float
                    description: Time in seconds it took to complete the request.
                  usage:
                    type: object
                    properties:
                      credits:
                        type: integer
                        description: Credit usage details for the request.
                  request_id:
                    type: string
                    description: Unique request identifier.
      operationId: postTavilyCrawl
  /apis/v1/tavily/extract:
    post:
      tags:
        - https://docs.tavily.com/documentation/api-reference/endpoint/extract
      summary: Extract web page content from specified URLs using Tavily Extract.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                urls:
                  type: array
                  items:
                    type: string
                  description: The URLs to extract content from.
                  example:
                    - https://en.wikipedia.org/wiki/Artificial_intelligence
                query:
                  type: string
                  description: User intent for reranking extracted content chunks.
                chunks_per_source:
                  type: integer
                  default: 3
                  description: Maximum number of relevant chunks returned per source.
                  minimum: 1
                  maximum: 5
                extract_depth:
                  type: string
                  enum:
                    - basic
                    - advanced
                  default: basic
                  description: Depth of the extraction process.
                include_images:
                  type: boolean
                  default: false
                  description: Include a list of images extracted from the URLs.
                include_favicon:
                  type: boolean
                  default: false
                  description: Include the favicon URL for each result.
                format:
                  type: string
                  enum:
                    - markdown
                    - text
                  default: markdown
                  description: Format of the extracted web page content.
                timeout:
                  type: number
                  format: float
                  description: Maximum time in seconds to wait for the URL extraction.
                  minimum: 1
                  maximum: 60
                include_usage:
                  type: boolean
                  default: false
                  description: Include credit usage information in the response.
              required:
                - urls
      responses:
        '200':
          description: Extraction results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          description: URL of the extracted content.
                        raw_content:
                          type: string
                          description: Extracted raw content from the URL.
                        favicon:
                          type: string
                          description: Favicon URL of the extracted content.
                  failed_results:
                    type: array
                    items:
                      type: string
                    description: List of URLs that could not be processed.
                  response_time:
                    type: number
                    format: float
                    description: Time in seconds it took to complete the request.
                  usage:
                    type: object
                    properties:
                      credits:
                        type: integer
                        description: Credit usage details for the request.
                  request_id:
                    type: string
                    description: Unique request identifier.
      operationId: postTavilyExtract
  /apis/v1/tavily/map:
    post:
      tags:
        - https://docs.tavily.com/documentation/api-reference/endpoint/map
      summary: Generate comprehensive site maps using Tavily Map.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The root URL to begin the mapping.
                  example: docs.tavily.com
                instructions:
                  type: string
                  description: Natural language instructions for the crawler.
                max_depth:
                  type: integer
                  default: 1
                  description: Max depth of the mapping.
                  minimum: 1
                  maximum: 5
                max_breadth:
                  type: integer
                  default: 20
                  description: Max number of links to follow per level of the tree.
                  minimum: 1
                  maximum: 500
                limit:
                  type: integer
                  default: 50
                  description: Total number of links the crawler will process before stopping.
                  minimum: 1
                select_paths:
                  type: array
                  items:
                    type: string
                  description: Regex patterns to select only URLs with specific path patterns.
                select_domains:
                  type: array
                  items:
                    type: string
                  description: Regex patterns to select crawling to specific domains or subdomains.
                exclude_paths:
                  type: array
                  items:
                    type: string
                  description: Regex patterns to exclude URLs with specific path patterns.
                exclude_domains:
                  type: array
                  items:
                    type: string
                  description: Regex patterns to exclude specific domains or subdomains from mapping.
                allow_external:
                  type: boolean
                  default: true
                  description: Include external domain links in the final results list.
                timeout:
                  type: number
                  format: float
                  default: 150
                  description: Maximum time in seconds to wait for the map operation.
                  minimum: 10
                  maximum: 150
                include_usage:
                  type: boolean
                  default: false
                  description: Include credit usage information in the response.
              required:
                - url
      responses:
        '200':
          description: Map results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  base_url:
                    type: string
                    description: The base URL that was mapped.
                  results:
                    type: array
                    items:
                      type: string
                      description: URLs discovered during the mapping.
                  response_time:
                    type: number
                    format: float
                    description: Time in seconds it took to complete the request.
                  usage:
                    type: object
                    properties:
                      credits:
                        type: integer
                        description: Credit usage details for the request.
                  request_id:
                    type: string
                    description: Unique request identifier.
      operationId: postTavilyMap
  /apis/v1/tavily/search:
    post:
      tags:
        - https://docs.tavily.com/documentation/api-reference/endpoint/search
      summary: Execute a search query using Tavily Search.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The search query to execute with Tavily.
                  example: Who is Leo Messi?
                search_depth:
                  type: string
                  enum:
                    - advanced
                    - basic
                    - fast
                    - ultra-fast
                  default: basic
                  description: Controls the latency vs. relevance tradeoff.
                chunks_per_source:
                  type: integer
                  default: 3
                  description: Maximum number of relevant chunks returned per source.
                  minimum: 1
                  maximum: 3
                max_results:
                  type: integer
                  default: 5
                  description: Maximum number of search results to return.
                  minimum: 0
                  maximum: 20
                topic:
                  type: string
                  enum:
                    - general
                    - news
                    - finance
                  default: general
                  description: Category of the search.
                time_range:
                  type: string
                  enum:
                    - day
                    - week
                    - month
                    - year
                    - d
                    - w
                    - m
                    - 'y'
                  description: Time range to filter results based on publish date.
                start_date:
                  type: string
                  format: date
                  description: Return results after the specified start date.
                  example: '2025-02-09'
                end_date:
                  type: string
                  format: date
                  description: Return results before the specified end date.
                  example: '2025-12-29'
                include_answer:
                  type: boolean
                  default: false
                  description: Include an LLM-generated answer to the query.
                include_raw_content:
                  type: boolean
                  default: false
                  description: Include cleaned and parsed HTML content of each search result.
                include_images:
                  type: boolean
                  default: false
                  description: Perform an image search and include results.
                include_image_descriptions:
                  type: boolean
                  default: false
                  description: Add descriptive text for each image when include_images is true.
                include_favicon:
                  type: boolean
                  default: false
                  description: Include the favicon URL for each result.
                include_domains:
                  type: array
                  items:
                    type: string
                  description: List of domains to specifically include in the search results.
                  maxItems: 300
                exclude_domains:
                  type: array
                  items:
                    type: string
                  description: List of domains to specifically exclude from the search results.
                  maxItems: 150
                country:
                  type: string
                  description: Boost search results from a specific country.
                  enum:
                    - afghanistan
                    - albania
                    - algeria
                    - andorra
                    - angola
                    - argentina
                    - armenia
                    - australia
                    - austria
                    - azerbaijan
                    - bahamas
                    - bahrain
                    - bangladesh
                    - barbados
                    - belarus
                    - belgium
                    - belize
                    - benin
                    - bhutan
                    - bolivia
                    - bosnia and herzegovina
                    - botswana
                    - brazil
                    - brunei
                    - bulgaria
                    - burkina faso
                    - burundi
                    - cambodia
                    - cameroon
                    - canada
                    - cape verde
                    - central african republic
                    - chad
                    - chile
                    - china
                    - colombia
                    - comoros
                    - congo
                    - costa rica
                    - croatia
                    - cuba
                    - cyprus
                    - czech republic
                    - denmark
                    - djibouti
                    - dominican republic
                    - ecuador
                    - egypt
                    - el salvador
                    - equatorial guinea
                    - eritrea
                    - estonia
                    - ethiopia
                    - fiji
                    - finland
                    - france
                    - gabon
                    - gambia
                    - georgia
                    - germany
                    - ghana
                    - greece
                    - guatemala
                    - guinea
                    - haiti
                    - honduras
                    - hungary
                    - iceland
                    - india
                    - indonesia
                    - iran
                    - iraq
                    - ireland
                    - israel
                    - italy
                    - jamaica
                    - japan
                    - jordan
                    - kazakhstan
                    - kenya
                    - kuwait
                    - kyrgyzstan
                    - latvia
                    - lebanon
                    - lesotho
                    - liberia
                    - libya
                    - liechtenstein
                    - lithuania
                    - luxembourg
                    - madagascar
                    - malawi
                    - malaysia
                    - maldives
                    - mali
                    - malta
                    - mauritania
                    - mauritius
                    - mexico
                    - moldova
                    - monaco
                    - mongolia
                    - montenegro
                    - morocco
                    - mozambique
                    - myanmar
                    - namibia
                    - nepal
                    - netherlands
                    - new zealand
                    - nicaragua
                    - niger
                    - nigeria
                    - north korea
                    - north macedonia
                    - norway
                    - oman
                    - pakistan
                    - panama
                    - papua new guinea
                    - paraguay
                    - peru
                    - philippines
                    - poland
                    - portugal
                    - qatar
                    - romania
                    - russia
                    - rwanda
                    - saudi arabia
                    - senegal
                    - serbia
                    - singapore
                    - slovakia
                    - slovenia
                    - somalia
                    - south africa
                    - south korea
                    - south sudan
                    - spain
                    - sri lanka
                    - sudan
                    - sweden
                    - switzerland
                    - syria
                    - taiwan
                    - tajikistan
                    - tanzania
                    - thailand
                    - togo
                    - trinidad and tobago
                    - tunisia
                    - turkey
                    - turkmenistan
                    - uganda
                    - ukraine
                    - united arab emirates
                    - united kingdom
                    - united states
                    - uruguay
                    - uzbekistan
                    - venezuela
                    - vietnam
                    - yemen
                    - zambia
                    - zimbabwe
                auto_parameters:
                  type: boolean
                  default: false
                  description: Automatically configure search parameters based on query content.
                include_usage:
                  type: boolean
                  default: false
                  description: Include credit usage information in the response.
              required:
                - query
      responses:
        '200':
          description: Search results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                    description: The search query that was executed.
                  answer:
                    type: string
                    description: A short answer to the user's query, generated by an LLM.
                  images:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          description: Image URL.
                        description:
                          type: string
                          description: Image description.
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                          description: Title of the search result.
                        url:
                          type: string
                          description: URL of the search result.
                        content:
                          type: string
                          description: Content snippet of the search result.
                        score:
                          type: number
                          format: float
                          description: Relevance score of the search result.
                        favicon:
                          type: string
                          description: Favicon URL of the search result.
                  response_time:
                    type: number
                    format: float
                    description: Time in seconds it took to complete the request.
                  usage:
                    type: object
                    properties:
                      credits:
                        type: integer
                        description: Credit usage details for the request.
                  request_id:
                    type: string
                    description: Unique request identifier.
      operationId: postTavilySearch
  /apis/v1/twitter/article:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_article
      summary: Get Article
      description: Get article by tweet ID.
      parameters:
        - name: tweet_id
          in: query
          required: true
          schema:
            type: string
          description: The tweet ID of the article.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleResponse'
      operationId: getTwitterArticle
  /apis/v1/twitter/auth_twitter:
    post:
      summary: Link an X/Twitter account (start OAuth)
      description: >-
        Start the OAuth flow that links a user's X/Twitter account to the AIsa API key on the request. Call this once
        per source user. AIsa returns an authorization URL — the user opens it in a browser, approves the requested
        scopes, and X redirects back to AIsa's fixed callback. AIsa stores the resulting session against your API key,
        and every subsequent Twitter write call (e.g., `POST /twitter/follow_twitter`) uses that session automatically.


        The returned `auth_url` is short-lived; generate a fresh one every time the user needs to (re-)link.
      operationId: authTwitterUser
      security:
        - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                scopes:
                  type: array
                  items:
                    type: string
                  description: >-
                    Optional list of X OAuth 2.0 scopes to request. Defaults to the set required by AIsa's Twitter write
                    endpoints: `follows.write`, `tweet.read`, `users.read`, `tweet.write`, `like.write`, `dm.read`,
                    `dm.write`.
                  example:
                    - follows.write
                    - tweet.read
                    - users.read
            example: {}
      responses:
        '200':
          description: Authorization URL generated.
          content:
            application/json:
              schema:
                type: object
                required:
                  - auth_url
                  - state
                properties:
                  auth_url:
                    type: string
                    format: uri
                    description: >-
                      Short-lived X OAuth authorization URL. Open it in a browser so the source user can approve the
                      requested scopes.
                  state:
                    type: string
                    description: >-
                      Opaque CSRF state token that AIsa will validate when X redirects back to its callback. Store it
                      client-side if you need to correlate the flow.
                  expires_at:
                    type: string
                    format: date-time
                    description: >-
                      When the `auth_url` expires. Request a new one if the user hasn't completed the flow before this
                      time.
              example:
                auth_url: >-
                  https://twitter.com/i/oauth2/authorize?response_type=code&client_id=AIsa&redirect_uri=https%3A%2F%2Fapi.aisa.one%2Fapis%2Fv1%2Ftwitter%2Foauth_callback&scope=follows.write%20tweet.read%20users.read&state=0c2...d1f&code_challenge=...&code_challenge_method=S256
                state: 0c2ad1f...
                expires_at: '2026-04-18T07:00:00Z'
        '400':
          description: Invalid `scopes` list — contains an unsupported scope.
        '401':
          description: Missing or invalid AIsa API key.
        '429':
          description: Rate limit hit.
        '500':
          description: Internal error generating the OAuth URL.
      tags:
        - Twitter / X
  /apis/v1/twitter/community/get_tweets_from_all_community:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_all_community_tweets
      summary: Search Tweets From All Communities
      description: Search tweets from all communities.
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          description: Search query (e.g., keyword)
        - name: queryType
          in: query
          required: true
          schema:
            type: string
            enum:
              - Latest
              - Top
            default: Latest
          description: Query type (Latest or Top)
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination
      responses:
        '200':
          description: Tweets response
          content:
            application/json:
              schema:
                type: object
                properties:
                  tweets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tweet'
                  has_next_page:
                    type: boolean
                  next_cursor:
                    type: string
      operationId: getTwitterCommunityGetTweetsFromAllCommunity
  /apis/v1/twitter/community/info:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_community_by_id
      summary: Get Community Info By Id
      description: Retrieve information about a community by its ID.
      parameters:
        - name: community_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the community
      responses:
        '200':
          description: Community info response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityInfo'
      operationId: getTwitterCommunityInfo
  /apis/v1/twitter/community/members:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_community_members
      summary: Get Community Members
      description: Retrieve members of a community.
      parameters:
        - name: community_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the community
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination
      responses:
        '200':
          description: Community members response
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  has_next_page:
                    type: boolean
                  next_cursor:
                    type: string
      operationId: getTwitterCommunityMembers
  /apis/v1/twitter/community/moderators:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_community_moderators
      summary: Get Community Moderators
      description: Retrieve moderators of a community.
      parameters:
        - name: community_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the community
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination
      responses:
        '200':
          description: Community moderators response
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  has_next_page:
                    type: boolean
                  next_cursor:
                    type: string
      operationId: getTwitterCommunityModerators
  /apis/v1/twitter/community/tweets:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_community_tweets
      summary: Get Community Tweets
      description: Retrieve tweets of a community.
      parameters:
        - name: community_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the community
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination
      responses:
        '200':
          description: Community tweets response
          content:
            application/json:
              schema:
                type: object
                properties:
                  tweets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tweet'
                  has_next_page:
                    type: boolean
                  next_cursor:
                    type: string
      operationId: getTwitterCommunityTweets
  /apis/v1/twitter/follow_twitter:
    post:
      summary: Follow a user on X/Twitter
      description: >-
        Make the authenticated source user follow the given target user on X/Twitter. Mirrors the [official X v2 `POST
        /2/users/{id}/following` endpoint](https://docs.x.com/x-api/users/follow-user), routed through the AIsa gateway.


        **Authentication.** This is a write action that requires an OAuth session for the source user, attached to your
        AIsa API key. Link your X account once by calling `POST /apis/v1/twitter/auth_twitter` — AIsa then uses that
        session automatically for every write request sent with your key.


        **Scopes.** The underlying X session must hold `follows.write`, `tweet.read`, and `users.read`.
      operationId: followTwitterUser
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - target_user_id
              properties:
                target_user_id:
                  type: string
                  description: Numeric ID of the X/Twitter user to follow. Must match the X regex `^[0-9]{1,19}$`.
                  pattern: ^[0-9]{1,19}$
                  example: '6253282'
            examples:
              follow_user:
                summary: Follow @TwitterDev (id 2244994945)
                value:
                  target_user_id: '2244994945'
      responses:
        '200':
          description: Follow succeeded (or was already in place).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      following:
                        type: boolean
                        description: '`true` when the source user now follows the target user.'
                      pending_follow:
                        type: boolean
                        description: '`true` when a follow request has been sent to a protected account and is awaiting approval.'
              example:
                data:
                  following: true
                  pending_follow: false
        '400':
          description: Invalid request — missing or malformed `target_user_id`.
        '401':
          description: Missing or invalid AIsa API key.
        '403':
          description: OAuth session missing, expired, or lacking the `follows.write` scope. Re-authorize from the dashboard.
        '429':
          description: Rate limit hit — either your AIsa key's RPM cap or the upstream X rate limit.
        '500':
          description: Internal error.
        '502':
          description: Upstream X API unreachable or returned an error. Safe to retry with exponential backoff.
      tags:
        - Twitter / X
  /apis/v1/twitter/like_twitter:
    post:
      summary: Like a tweet
      description: >-
        Like a tweet on behalf of the authenticated source user. Mirrors the [official X v2 `POST /2/users/{id}/likes`
        endpoint](https://docs.x.com/x-api/users/like-post), routed through the AIsa gateway.


        **Authentication.** Requires an OAuth session for the source user, attached to your AIsa API key. Link the
        account once via `POST /apis/v1/twitter/auth_twitter`.


        **Scopes.** The underlying X session must hold `like.write`, `tweet.read`, and `users.read`.


        Liking a tweet already liked is a no-op and still returns `200` with `liked: true`.
      operationId: likeTwitter
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tweet_id
              properties:
                tweet_id:
                  type: string
                  description: Numeric ID of the tweet to like. Must match X's regex `^[0-9]{1,19}$`.
                  pattern: ^[0-9]{1,19}$
                  example: '1346889436626259968'
            examples:
              like_tweet:
                summary: Like tweet 1346889436626259968
                value:
                  tweet_id: '1346889436626259968'
      responses:
        '200':
          description: Like succeeded (or was already in place).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      liked:
                        type: boolean
                        description: '`true` once the source user has liked the target tweet.'
              example:
                data:
                  liked: true
        '400':
          description: Invalid request — missing or malformed `tweet_id`.
        '401':
          description: Missing or invalid AIsa API key.
        '403':
          description: >-
            OAuth session missing, expired, or lacking `like.write`. Re-authorize via `POST
            /apis/v1/twitter/auth_twitter`.
        '404':
          description: Tweet not found or not visible to the source user.
        '429':
          description: Rate limit hit — either your AIsa key's RPM cap or the upstream X rate limit.
        '500':
          description: Internal error.
        '502':
          description: Upstream X API unreachable. Safe to retry with exponential backoff.
      tags:
        - Twitter / X
  /apis/v1/twitter/list/followers:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_list_followers
      summary: Get List Followers
      description: Get followers of a list. Page size is 20.
      parameters:
        - name: list_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the list
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor of the page
      responses:
        '200':
          description: List followers of the list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TwitterListFollowersResponse'
      operationId: getTwitterListFollowers
  /apis/v1/twitter/list/members:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_list_members
      summary: Get List Members
      description: Get members of a list. Page size is 20.
      parameters:
        - name: list_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the list
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor of the page
      responses:
        '200':
          description: List members response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TwitterListMembersResponse'
      operationId: getTwitterListMembers
  /apis/v1/twitter/post_twitter:
    post:
      summary: Post or edit a tweet
      description: >-
        Publish a new tweet on behalf of the authenticated source user, or edit an existing tweet. Mirrors the [official
        X v2 `POST /2/tweets` endpoint](https://docs.x.com/x-api/posts/create-post), routed through the AIsa gateway.


        **Authentication.** Requires an OAuth session for the source user, attached to your AIsa API key. Link the
        account once via `POST /apis/v1/twitter/auth_twitter`.


        **Scopes.** The underlying X session must hold `tweet.read`, `tweet.write`, and `users.read`.


        **Mutually exclusive fields.** `media`, `poll`, `quote_tweet_id`, and `card_uri` cannot be combined in the same
        request. At most one of them may be set.
      operationId: postTwitter
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: The content of the tweet. Optional when posting media, a poll, or a quote tweet; required otherwise.
                  example: Hello from AIsa — shipping agent-friendly Twitter APIs.
                reply:
                  type: object
                  description: Post as a reply to another tweet.
                  required:
                    - in_reply_to_tweet_id
                  properties:
                    in_reply_to_tweet_id:
                      type: string
                      description: Tweet ID being replied to.
                      pattern: ^[0-9]{1,19}$
                    auto_populate_reply_metadata:
                      type: boolean
                      description: Auto-populate reply @-mentions from the original tweet.
                    exclude_reply_user_ids:
                      type: array
                      items:
                        type: string
                        pattern: ^[0-9]{1,19}$
                      maxItems: 10
                      description: User IDs to exclude from reply auto-mentions (max 10).
                quote_tweet_id:
                  type: string
                  description: Tweet ID to quote. Mutually exclusive with `media`, `poll`, and `card_uri`.
                  pattern: ^[0-9]{1,19}$
                media:
                  type: object
                  description: Attach media. Mutually exclusive with `poll`, `quote_tweet_id`, and `card_uri`.
                  required:
                    - media_ids
                  properties:
                    media_ids:
                      type: array
                      items:
                        type: string
                      minItems: 1
                      maxItems: 4
                      description: 1–4 media IDs from the X media-upload API.
                    tagged_user_ids:
                      type: array
                      items:
                        type: string
                        pattern: ^[0-9]{1,19}$
                      maxItems: 10
                      description: User IDs tagged in the media (max 10).
                poll:
                  type: object
                  description: Attach a poll. Mutually exclusive with `media`, `quote_tweet_id`, and `card_uri`.
                  required:
                    - options
                    - duration_minutes
                  properties:
                    options:
                      type: array
                      items:
                        type: string
                        maxLength: 25
                      minItems: 2
                      maxItems: 4
                      description: 2–4 poll choices, each 1–25 characters.
                    duration_minutes:
                      type: integer
                      minimum: 5
                      maximum: 10080
                      description: Poll duration in minutes (5–10080, i.e. up to 7 days).
                    reply_settings:
                      type: string
                      enum:
                        - following
                        - mentionedUsers
                        - subscribers
                        - verified
                card_uri:
                  type: string
                  description: Card URI. Mutually exclusive with `media`, `poll`, `quote_tweet_id`, and `direct_message_deep_link`.
                direct_message_deep_link:
                  type: string
                  description: Deep link that takes the conversation into a private DM.
                geo:
                  type: object
                  description: Attach a place to the tweet.
                  properties:
                    place_id:
                      type: string
                      description: X place ID.
                reply_settings:
                  type: string
                  enum:
                    - following
                    - mentionedUsers
                    - subscribers
                    - verified
                  description: Who is allowed to reply.
                for_super_followers_only:
                  type: boolean
                  default: false
                  description: Only visible to super followers.
                nullcast:
                  type: boolean
                  default: false
                  description: Nullcast (promoted-only) tweet — not shown in the public timeline or to followers.
                paid_partnership:
                  type: boolean
                  description: Marks the tweet as a paid partnership.
                made_with_ai:
                  type: boolean
                  description: Flags the tweet as containing AI-generated media.
                community_id:
                  type: string
                  pattern: ^[0-9]{1,19}$
                  description: Post into the specified community.
                share_with_followers:
                  type: boolean
                  default: false
                  description: Also share the community post with your followers.
                edit_options:
                  type: object
                  description: Edit an existing tweet instead of creating a new one (subject to X's edit window).
                  required:
                    - previous_post_id
                  properties:
                    previous_post_id:
                      type: string
                      pattern: ^[0-9]{1,19}$
                      description: Tweet ID to edit.
            examples:
              simple_text:
                summary: Plain text tweet
                value:
                  text: Hello, World!
              reply:
                summary: Reply to a tweet
                value:
                  text: Totally agree 👌
                  reply:
                    in_reply_to_tweet_id: '1234567890123456789'
                    auto_populate_reply_metadata: true
              with_poll:
                summary: Tweet with a poll
                value:
                  text: 'Pick your favorite:'
                  poll:
                    options:
                      - Option A
                      - Option B
                      - Option C
                    duration_minutes: 60
              with_media:
                summary: Tweet with media
                value:
                  text: Ship log 📸
                  media:
                    media_ids:
                      - '1146654567674912769'
                    tagged_user_ids:
                      - '2244994945'
              quote:
                summary: Quote tweet
                value:
                  text: 'Worth reading:'
                  quote_tweet_id: '1234567890123456789'
              edit:
                summary: Edit an existing tweet
                value:
                  text: Updated tweet content (typo fixed).
                  edit_options:
                    previous_post_id: '1234567890123456789'
      responses:
        '201':
          description: Tweet created (or edited) successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        pattern: ^[0-9]{1,19}$
                        description: ID of the newly created or edited tweet.
                      text:
                        type: string
                        description: Final text of the tweet as stored by X.
              example:
                data:
                  id: '1346889436626259968'
                  text: Hello, World!
        '400':
          description: Invalid request — violated a mutual-exclusivity rule, missing required field, or text too long.
        '401':
          description: Missing or invalid AIsa API key.
        '403':
          description: >-
            OAuth session missing, expired, or lacking `tweet.write`. Re-authorize via `POST
            /apis/v1/twitter/auth_twitter`.
        '404':
          description: Referenced tweet (reply, quote, or edit target) not found.
        '409':
          description: Conflict — e.g., duplicate tweet content or edit outside the allowed window.
        '429':
          description: Rate limit hit.
        '500':
          description: Internal error.
        '502':
          description: Upstream X API unreachable.
      tags:
        - Twitter / X
  /apis/v1/twitter/spaces/detail:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_space_detail
      summary: Get Space Detail
      description: Get details of a Twitter Space by its ID.
      parameters:
        - name: space_id
          in: query
          required: true
          schema:
            type: string
          description: The ID of the space.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaceDetailResponse'
      operationId: getTwitterSpacesDetail
  /apis/v1/twitter/trends:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_trends
      summary: Get Trends
      description: Get trends by WOEID.
      parameters:
        - name: woeid
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: 'The WOEID of the location. Example: 2418046.'
        - name: count
          in: query
          required: false
          schema:
            type: integer
            format: int64
            default: 30
            minimum: 30
          description: The number of trends to return. Default is 30.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendsResponse'
      operationId: getTwitterTrends
  /apis/v1/twitter/tweet/advanced_search:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/tweet_advanced_search
      summary: Advanced Search
      description: Advanced search for tweets.
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          description: The query to search for.
        - name: queryType
          in: query
          required: true
          schema:
            type: string
            enum:
              - Latest
              - Top
            default: Latest
          description: The query type to search for.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: The cursor to paginate through the results. First page is empty.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedSearchResponse'
      operationId: getTwitterTweetAdvancedSearch
  /apis/v1/twitter/tweet/quotes:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_tweet_quote
      summary: Get Tweet Quotations
      parameters:
        - name: tweetId
          in: query
          required: true
          schema:
            type: string
          description: The tweet ID to get quotes for.
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  tweets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tweet'
                  has_next_page:
                    type: boolean
                  next_cursor:
                    type: string
                  status:
                    type: string
                  message:
                    type: string
      operationId: getTwitterTweetQuotes
  /apis/v1/twitter/tweet/replies:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_tweet_reply
      summary: Get Tweet Replies
      parameters:
        - name: tweetId
          in: query
          required: true
          schema:
            type: string
          description: The tweet ID to get replies for.
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  replies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tweet'
                  has_next_page:
                    type: boolean
                  next_cursor:
                    type: string
                  status:
                    type: string
                  message:
                    type: string
      operationId: getTwitterTweetReplies
  /apis/v1/twitter/tweet/retweeters:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_tweet_retweeter
      summary: Get Tweet Retweeters
      parameters:
        - name: tweetId
          in: query
          required: true
          schema:
            type: string
          description: The tweet ID to get retweeters for.
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  has_next_page:
                    type: boolean
                  next_cursor:
                    type: string
                  status:
                    type: string
                  message:
                    type: string
      operationId: getTwitterTweetRetweeters
  /apis/v1/twitter/tweet/thread_context:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_tweet_thread_context
      summary: Get Tweet Thread Context
      description: Get the thread context of a tweet.
      parameters:
        - name: tweetId
          in: query
          required: true
          schema:
            type: string
          description: The tweet ID to get. Can be a reply tweet or an original tweet.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: The cursor to paginate through the results. First page is empty.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TweetThreadContextResponse'
      operationId: getTwitterTweetThreadContext
  /apis/v1/twitter/tweets:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_tweet_by_ids
      summary: Get Tweets by IDs
      parameters:
        - name: tweet_ids
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
          description: Comma-separated list of tweet IDs.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  tweets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tweet'
                  status:
                    type: string
                  message:
                    type: string
      operationId: getTwitterTweets
  /apis/v1/twitter/unfollow_twitter:
    post:
      summary: Unfollow a user on X/Twitter
      description: >-
        Make the authenticated source user unfollow the given target user on X/Twitter. Mirrors the [official X v2
        `DELETE /2/users/{source_user_id}/following/{target_user_id}`
        endpoint](https://docs.x.com/x-api/users/unfollow-user), routed through the AIsa gateway. Uses POST (not DELETE)
        for consistency with the other AIsa Twitter write actions.


        **Authentication.** Requires an OAuth session for the source user, attached to your AIsa API key. Link the
        account once via `POST /apis/v1/twitter/auth_twitter`.


        **Scopes.** The underlying X session must hold `follows.write`, `tweet.read`, and `users.read`.


        Unfollowing a user you don't currently follow is a no-op and still returns `200` with `following: false`.
      operationId: unfollowTwitterUser
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - target_user_id
              properties:
                target_user_id:
                  type: string
                  description: Numeric ID of the X/Twitter user to unfollow. Must match the X regex `^[0-9]{1,19}$`.
                  pattern: ^[0-9]{1,19}$
                  example: '2244994945'
            examples:
              unfollow_user:
                summary: Unfollow @TwitterDev (id 2244994945)
                value:
                  target_user_id: '2244994945'
      responses:
        '200':
          description: Unfollow succeeded (or the source user wasn't following the target to begin with).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      following:
                        type: boolean
                        description: '`false` once the source user no longer follows the target user.'
              example:
                data:
                  following: false
        '400':
          description: Invalid request — missing or malformed `target_user_id`.
        '401':
          description: Missing or invalid AIsa API key.
        '403':
          description: >-
            OAuth session missing, expired, or lacking the `follows.write` scope. Re-authorize via `POST
            /apis/v1/twitter/auth_twitter`.
        '429':
          description: Rate limit hit — either your AIsa key's RPM cap or the upstream X rate limit.
        '500':
          description: Internal error.
        '502':
          description: Upstream X API unreachable or returned an error. Safe to retry with exponential backoff.
      tags:
        - Twitter / X
  /apis/v1/twitter/unlike_twitter:
    post:
      summary: Unlike a tweet
      description: >-
        Remove the source user's like from a tweet. Mirrors the [official X v2 `DELETE /2/users/{id}/likes/{tweet_id}`
        endpoint](https://docs.x.com/x-api/users/unlike-post), routed through the AIsa gateway. Uses POST (not DELETE)
        for consistency with the other AIsa Twitter write actions.


        **Authentication.** Requires an OAuth session for the source user, attached to your AIsa API key. Link the
        account once via `POST /apis/v1/twitter/auth_twitter`.


        **Scopes.** The underlying X session must hold `like.write`, `tweet.read`, and `users.read`.


        Unliking a tweet the source user has not liked is a no-op and still returns `200` with `liked: false`.
      operationId: unlikeTwitter
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tweet_id
              properties:
                tweet_id:
                  type: string
                  description: Numeric ID of the tweet to unlike. Must match X's regex `^[0-9]{1,19}$`.
                  pattern: ^[0-9]{1,19}$
                  example: '1346889436626259968'
            examples:
              unlike_tweet:
                summary: Unlike tweet 1346889436626259968
                value:
                  tweet_id: '1346889436626259968'
      responses:
        '200':
          description: Unlike succeeded (or the source user hadn't liked the tweet to begin with).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      liked:
                        type: boolean
                        description: '`false` once the like has been removed.'
              example:
                data:
                  liked: false
        '400':
          description: Invalid request — missing or malformed `tweet_id`.
        '401':
          description: Missing or invalid AIsa API key.
        '403':
          description: >-
            OAuth session missing, expired, or lacking `like.write`. Re-authorize via `POST
            /apis/v1/twitter/auth_twitter`.
        '404':
          description: Tweet not found or not visible to the source user.
        '429':
          description: Rate limit hit.
        '500':
          description: Internal error.
        '502':
          description: Upstream X API unreachable. Safe to retry with exponential backoff.
      tags:
        - Twitter / X
  /apis/v1/twitter/user/batch_info_by_ids:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/batch_get_user_by_userids
      summary: Batch Get User Info By UserIds
      parameters:
        - name: userIds
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated user IDs
      responses:
        '200':
          description: Batch user information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUserInfoResponse'
      operationId: getTwitterUserBatchInfoByIds
  /apis/v1/twitter/user/check_follow_relationship:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/check_follow_relationship
      summary: Check Follow Relationship
      description: Check if the user is following/followed by the target user.
      parameters:
        - name: source_user_name
          in: query
          required: true
          schema:
            type: string
          description: Screen name of the source user.
        - name: target_user_name
          in: query
          required: true
          schema:
            type: string
          description: Screen name of the target user.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FollowRelationshipResponse'
      operationId: getTwitterUserCheckFollowRelationship
  /apis/v1/twitter/user/followers:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_user_followers
      summary: Get User Followers
      parameters:
        - name: userName
          in: query
          required: true
          schema:
            type: string
          description: Screen name of the user
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 200
            minimum: 20
            maximum: 200
          description: Number of followers per page
      responses:
        '200':
          description: User followers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUserInfoResponse'
      operationId: getTwitterUserFollowers
  /apis/v1/twitter/user/followings:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_user_followings
      summary: Get User Followings
      description: Get user followings. Each page returns exactly 200 followings. Use cursor for pagination.
      parameters:
        - name: userName
          in: query
          required: true
          schema:
            type: string
          description: Screen name of the user.
        - name: cursor
          in: query
          schema:
            type: string
          description: The cursor to paginate through the results. First page is empty.
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 200
            minimum: 20
            maximum: 200
          description: The number of followings to return per page.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFollowingsResponse'
      operationId: getTwitterUserFollowings
  /apis/v1/twitter/user/info:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_user_by_username
      summary: Get User Info
      parameters:
        - name: userName
          in: query
          required: true
          schema:
            type: string
          description: The screen name of the user
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUserInfoResponse'
      operationId: getTwitterUserInfo
  /apis/v1/twitter/user/last_tweets:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_user_last_tweets
      summary: Get User Last Tweets
      parameters:
        - name: userId
          in: query
          schema:
            type: string
          description: User ID of the user
        - name: userName
          in: query
          schema:
            type: string
          description: Screen name of the user
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination
        - name: includeReplies
          in: query
          schema:
            type: boolean
            default: false
          description: Include replies in the results
      responses:
        '200':
          description: User tweets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTweetsResponse'
      operationId: getTwitterUserLastTweets
  /apis/v1/twitter/user/mentions:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_user_mention
      summary: Get User Mentions
      description: Get tweet mentions by user screen name. Each page returns exactly 20 mentions.
      parameters:
        - name: userName
          in: query
          required: true
          schema:
            type: string
          description: The user screen name to get mentions for.
        - name: sinceTime
          in: query
          schema:
            type: integer
            format: int64
          description: On or after a specified unix timestamp in seconds.
        - name: untilTime
          in: query
          schema:
            type: integer
            format: int64
          description: Before a specified unix timestamp in seconds.
        - name: cursor
          in: query
          schema:
            type: string
          description: The cursor to paginate through the results. First page is empty.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserMentionsResponse'
      operationId: getTwitterUserMentions
  /apis/v1/twitter/user/search:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/search_user
      summary: Search User by Keyword
      description: Search user by keyword.
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          description: The keyword to search.
        - name: cursor
          in: query
          schema:
            type: string
          description: The cursor to paginate through the results. First page is empty.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchUserResponse'
      operationId: getTwitterUserSearch
  /apis/v1/twitter/user/verifiedFollowers:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_user_verified_followers
      summary: Get User Verified Followers
      description: Get user verified followers in reverse chronological order.
      parameters:
        - name: user_id
          in: query
          required: true
          schema:
            type: string
          description: User ID of the user.
        - name: cursor
          in: query
          schema:
            type: string
          description: The cursor to paginate through the results. First page is empty.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedFollowersResponse'
      operationId: getTwitterUserVerifiedFollowers
  /apis/v1/twitter/user_about:
    get:
      tags:
        - https://docs.twitterapi.io/api-reference/endpoint/get_user_about
      summary: Get User Profile About
      parameters:
        - name: userName
          in: query
          required: true
          schema:
            type: string
          description: The screen name of the user
      responses:
        '200':
          description: User profile information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileAboutResponse'
      operationId: getTwitterUserAbout
  /apis/v1/youtube/search:
    get:
      summary: YouTube Search
      description: Perform a YouTube search via SearchApi
      tags:
        - YouTube Search
      parameters:
        - name: engine
          in: query
          required: true
          schema:
            type: string
            enum:
              - youtube
          description: Engine identifier for YouTube Search
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
        - name: sp
          in: query
          required: false
          schema:
            type: string
          description: YouTube filter token (pagination or advanced filters)
        - name: gl
          in: query
          required: false
          schema:
            type: string
          description: Country code (e.g. us, jp)
        - name: hl
          in: query
          required: false
          schema:
            type: string
          description: Interface language
      responses:
        '200':
          description: Successful YouTube search response
          content:
            application/json:
              schema:
                type: object
                description: YouTube search result payload
                properties:
                  search_metadata:
                    type: object
                    description: Search metadata
                  search_results:
                    type: array
                    items:
                      type: object
                      properties:
                        video_id:
                          type: string
                        title:
                          type: string
                        link:
                          type: string
                        channel_name:
                          type: string
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized / Invalid API key
      security:
        - bearerAuth: []
      operationId: getYoutubeSearch
  /v1/chat/completions:
    post:
      summary: Generate images via Chat Completions (wan2.7 family)
      description: >-
        Generate images with the Wan 2.7 image models. Request shape matches OpenAI Chat Completions with multimodal
        content; the response contains `choices[].message.content[]` where each item is `{type: "image", image: "<url or
        base64>"}`.


        **Important:** `messages[].content` must be an **array of typed parts**, not a plain string. Passing a string
        returns `400 invalid_parameter_error` with `Input should be a valid list: messages[*].content`.


        By default `wan2.7-image` returns **4 candidate images** (billed per image). Set `n` to request a different
        count.
      operationId: generateImageViaChat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - messages
              properties:
                model:
                  type: string
                  enum:
                    - wan2.7-image
                    - wan2.7-image-pro
                  description: >-
                    Image-generation model. `wan2.7-image` ($0.030/image) for standard quality, `wan2.7-image-pro`
                    ($0.075/image) for higher fidelity.
                messages:
                  type: array
                  description: >-
                    Conversation messages. Image prompts go in the last user message's `content` array as `{type:
                    "text"}` parts.
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - user
                          - assistant
                      content:
                        type: array
                        description: >-
                          Multimodal parts. For image generation, include at least one `{type: "text"}` part with the
                          prompt.
                        items:
                          type: object
                          required:
                            - type
                          properties:
                            type:
                              type: string
                              enum:
                                - text
                                - image_url
                            text:
                              type: string
                              description: 'Used when `type: "text"`.'
                            image_url:
                              type: object
                              description: 'Used when `type: "image_url"` (image-to-image use cases).'
                              properties:
                                url:
                                  type: string
                                  format: uri
                'n':
                  type: integer
                  minimum: 1
                  maximum: 4
                  default: 4
                  description: Number of images to generate. `wan2.7-image` returns 4 by default; pass `1` to save cost.
            examples:
              basic:
                summary: Single-image prompt (n=1)
                value:
                  model: wan2.7-image
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: A cute red panda, ultra-detailed, cinematic lighting
                  'n': 1
              four_variants:
                summary: Default 4 candidates for selection
                value:
                  model: wan2.7-image
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: A futuristic cyberpunk city, neon lights, rainy night, 8k
              pro:
                summary: Higher-fidelity pro model
                value:
                  model: wan2.7-image-pro
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: Oil painting of a rolling hillside at sunset, artstation
                  'n': 1
              image_to_image:
                summary: Image-to-image (reference + prompt)
                value:
                  model: wan2.7-image-pro
                  messages:
                    - role: user
                      content:
                        - type: image_url
                          image_url:
                            url: https://example.com/reference.jpg
                        - type: text
                          text: Transform into an oil painting in the style of Van Gogh
                  'n': 1
      responses:
        '200':
          description: Images generated. Returned as Chat Completion with `message.content[]` image parts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: chatcmpl-fcc86dfd-9424-9523-b0bd-cdf07383bee2
                  object:
                    type: string
                    example: chat.completion
                  created:
                    type: integer
                    example: 1776495713
                  model:
                    type: string
                    example: wan2.7-image
                  choices:
                    type: array
                    description: One entry per generated image.
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          nullable: true
                        finish_reason:
                          type: string
                          example: stop
                        message:
                          type: object
                          properties:
                            role:
                              type: string
                              example: assistant
                            content:
                              type: array
                              items:
                                type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - image
                                  image:
                                    type: string
                                    description: >-
                                      Short-lived URL to the generated image (or base64-encoded data, depending on your
                                      account configuration).
                  usage:
                    type: object
                    properties:
                      prompt_tokens:
                        type: integer
                      completion_tokens:
                        type: integer
                      total_tokens:
                        type: integer
              example:
                id: chatcmpl-fcc86dfd-9424-9523-b0bd-cdf07383bee2
                object: chat.completion
                created: 1776495713
                model: wan2.7-image
                choices:
                  - index: 0
                    finish_reason: stop
                    message:
                      role: assistant
                      content:
                        - type: image
                          image: https://cdn.aisa.one/images/wan2.7/20260418-abc.png
                usage:
                  prompt_tokens: 104
                  completion_tokens: 8
                  total_tokens: 112
        '400':
          description: >-
            Invalid request. Most common: `content` passed as a string instead of an array → `"Input should be a valid
            list: messages[*].content"`.
        '401':
          description: Missing or invalid AIsa API key.
        '429':
          description: Rate limit hit.
        '500':
          description: Internal error.
        '502':
          description: Upstream provider unreachable.
      tags:
        - AI Models
  /v1/images/generations:
    post:
      summary: Generate images (OpenAI-compatible)
      description: >-
        Generate images with the OpenAI-compatible images-generations endpoint. Currently routed to **ByteDance
        Seedream** — the Wan 2.7 family does not use this path.


        **Size constraint.** Seedream's upstream requires a minimum of **3,686,400 pixels** per image. Requests below
        that return `400 InvalidParameter: image size must be at least 3686400 pixels`. A 1024×1024 image (1,048,576 px)
        is rejected; 1920×1920 (3,686,400 px) and 2048×2048 (4,194,304 px) are accepted. Other aspect ratios are fine as
        long as `width × height ≥ 3,686,400`.
      operationId: createImageGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - prompt
              properties:
                model:
                  type: string
                  enum:
                    - seedream-4-5-251128
                  description: >-
                    Image generation model. Currently only `seedream-4-5-251128` is routed through this endpoint. Wan
                    2.7 models use `/v1/chat/completions`.
                prompt:
                  type: string
                  description: Text description of the image to generate.
                'n':
                  type: integer
                  minimum: 1
                  default: 1
                  description: Number of images to generate. Each image is billed separately at the per-image rate.
                size:
                  type: string
                  description: >-
                    Image dimensions as `WIDTHxHEIGHT`. Must satisfy `width × height ≥ 3,686,400`. Common valid values:
                    `1920x1920`, `2048x2048`, `2304x1600`, `2560x1920`.
                  example: 2048x2048
            examples:
              basic:
                summary: Single 2K image
                value:
                  model: seedream-4-5-251128
                  prompt: A cute red panda, ultra-detailed, cinematic lighting
                  'n': 1
                  size: 2048x2048
              minimum_size:
                summary: Exactly at minimum allowed size (1920×1920)
                value:
                  model: seedream-4-5-251128
                  prompt: A futuristic cyberpunk city, neon lights, rainy night, 8k
                  'n': 1
                  size: 1920x1920
              batch:
                summary: Four candidates for selection
                value:
                  model: seedream-4-5-251128
                  prompt: Oil painting of a rolling hillside at sunset
                  'n': 4
                  size: 2048x2048
      responses:
        '200':
          description: Images generated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  model:
                    type: string
                    example: seedream-4-5-251128
                  created:
                    type: integer
                    example: 1776495432
                  data:
                    type: array
                    description: One entry per generated image.
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: Short-lived URL to the generated image. Download and persist it; the URL expires.
                        size:
                          type: string
                          description: Actual dimensions of the returned image.
                  usage:
                    type: object
                    properties:
                      generated_images:
                        type: integer
                      output_tokens:
                        type: integer
                      total_tokens:
                        type: integer
              example:
                model: seedream-4-5-251128
                created: 1776495432
                data:
                  - url: https://cdn.aisa.one/images/seedream/20260418-abc.png
                    size: 2048x2048
                usage:
                  generated_images: 1
                  output_tokens: 16384
                  total_tokens: 16384
        '400':
          description: >-
            Invalid request. Most common: `size` smaller than 3,686,400 pixels → `"image size must be at least 3686400
            pixels"`.
        '401':
          description: Missing or invalid AIsa API key.
        '404':
          description: >-
            The model isn't routed through this endpoint. Wan 2.7 models return `openai_error` here — use
            `/v1/chat/completions` for those.
        '429':
          description: Rate limit hit.
        '500':
          description: Internal error.
        '502':
          description: Upstream provider unreachable.
      tags:
        - Image Generation
  /v1/messages:
    post:
      summary: Create a message
      description: >-
        Send a structured conversation to a Claude model and receive a response. Compatible with the Anthropic Messages
        API.
      operationId: createMessage
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - max_tokens
                - messages
              properties:
                model:
                  type: string
                  description: 'Claude model identifier. Examples: claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001.'
                  example: claude-sonnet-4-6
                max_tokens:
                  type: integer
                  description: Maximum number of tokens to generate before stopping.
                  example: 1024
                messages:
                  type: array
                  description: Conversation turns.
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - assistant
                      content:
                        description: String or array of content blocks.
                        oneOf:
                          - type: string
                          - type: array
                            items:
                              type: object
                  example:
                    - role: user
                      content: Hello, Claude
                system:
                  description: System prompt. String or array of text blocks.
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: object
                temperature:
                  type: number
                  format: float
                  minimum: 0
                  maximum: 1
                  default: 1
                  description: Randomness. 0 = deterministic, 1 = creative.
                top_p:
                  type: number
                  format: float
                  description: Nucleus sampling. Use instead of temperature.
                top_k:
                  type: integer
                  description: Only sample from the top K options for each token.
                stop_sequences:
                  type: array
                  items:
                    type: string
                  description: Custom sequences that stop generation.
                stream:
                  type: boolean
                  default: false
                  description: Enable SSE streaming.
                tools:
                  type: array
                  description: Tools the model may use.
                  items:
                    type: object
                    required:
                      - name
                      - input_schema
                    properties:
                      name:
                        type: string
                      description:
                        type: string
                      input_schema:
                        type: object
                      type:
                        type: string
                        example: custom
                tool_choice:
                  type: object
                  description: How the model uses tools.
                  properties:
                    type:
                      type: string
                      enum:
                        - auto
                        - any
                        - tool
                        - none
                    name:
                      type: string
                      description: Required when type is tool.
                    disable_parallel_tool_use:
                      type: boolean
                      default: false
                thinking:
                  type: object
                  description: Enable extended thinking for complex reasoning.
                  properties:
                    type:
                      type: string
                      enum:
                        - enabled
                    budget_tokens:
                      type: integer
                      example: 10000
                    display:
                      type: string
                      enum:
                        - summarized
                        - omitted
                metadata:
                  type: object
                  properties:
                    user_id:
                      type: string
                      description: External user ID (no PII).
                service_tier:
                  type: string
                  enum:
                    - auto
                    - standard_only
                  default: auto
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: msg_024e7cf42f5d47cfa6982b5ff8b55642
                  type:
                    type: string
                    example: message
                  role:
                    type: string
                    example: assistant
                  content:
                    type: array
                    description: Response content blocks (text, tool_use, thinking, etc.).
                    items:
                      type: object
                  model:
                    type: string
                    example: claude-sonnet-4-6
                  stop_reason:
                    type: string
                    enum:
                      - end_turn
                      - stop_sequence
                      - max_tokens
                      - tool_use
                  stop_sequence:
                    type: string
                    nullable: true
                  usage:
                    type: object
                    properties:
                      input_tokens:
                        type: integer
                      output_tokens:
                        type: integer
                      cache_creation_input_tokens:
                        type: integer
                      cache_read_input_tokens:
                        type: integer
        '400':
          description: Invalid request parameters
        '401':
          description: Missing or invalid API key
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
      tags:
        - AI Models
  /v1/models/{model}:generateContent:
    post:
      summary: Generate content using the specified Gemini model
      operationId: generateContent
      parameters:
        - name: model
          in: path
          required: true
          schema:
            type: string
          description: 'The name of the model to use, format: models/{model}'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateContentRequest'
      responses:
        '200':
          description: Successful content generation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateContentResponse'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      tags:
        - AI Models
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: AIsa API key from https://aisa.one/dashboard
  schemas:
    AdvancedSearchResponse:
      type: object
      properties:
        tweets:
          type: array
          items:
            $ref: '#/components/schemas/Tweet'
        has_next_page:
          type: boolean
        next_cursor:
          type: string
    AnalystEstimate:
      type: object
      properties:
        fiscal_period:
          type: string
          format: date
          description: The fiscal period of the analyst estimate.
        period:
          type: string
          enum:
            - annual
            - quarterly
          description: The period of the analyst estimate.
        revenue:
          type: integer
          description: The estimated revenue.
        earnings_per_share:
          type: number
          description: The estimated earnings per share.
    AnalystEstimatesResponse:
      type: object
      properties:
        analyst_estimates:
          type: array
          items:
            $ref: '#/components/schemas/AnalystEstimate'
    Article:
      type: object
      properties:
        author:
          $ref: '#/components/schemas/User'
        replyCount:
          type: integer
        likeCount:
          type: integer
        quoteCount:
          type: integer
        viewCount:
          type: integer
        createdAt:
          type: string
        title:
          type: string
        preview_text:
          type: string
        cover_media_img_url:
          type: string
        contents:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
    ArticleResponse:
      type: object
      properties:
        article:
          $ref: '#/components/schemas/Article'
        status:
          type: string
          enum:
            - success
            - failed
        message:
          type: string
    BalanceSheet:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol.
        report_period:
          type: string
          format: date
          description: The reporting period of the balance sheet.
        fiscal_period:
          type: string
          description: The fiscal period of the balance sheet.
        period:
          type: string
          enum:
            - quarterly
            - ttm
            - annual
          description: The time period of the balance sheet.
        currency:
          type: string
          description: The currency in which the financial data is reported.
        total_assets:
          type: number
          nullable: false
          description: The total assets of the company.
        current_assets:
          type: number
          nullable: false
          description: The current assets of the company.
        cash_and_equivalents:
          type: number
          nullable: false
          description: The cash and equivalents of the company.
        inventory:
          type: number
          nullable: false
          description: The inventory of the company.
        current_investments:
          type: number
          nullable: false
          description: The current investments of the company.
        trade_and_non_trade_receivables:
          type: number
          nullable: false
          description: The trade and non-trade receivables of the company.
        non_current_assets:
          type: number
          nullable: false
          description: The non-current assets of the company.
        property_plant_and_equipment:
          type: number
          nullable: false
          description: The property, plant, and equipment of the company.
        goodwill_and_intangible_assets:
          type: number
          nullable: false
          description: The goodwill and intangible assets of the company.
        investments:
          type: number
          nullable: false
          description: The investments of the company.
        non_current_investments:
          type: number
          nullable: false
          description: The non-current investments of the company.
        outstanding_shares:
          type: number
          nullable: false
          description: The outstanding shares of the company.
        tax_assets:
          type: number
          nullable: false
          description: The tax assets of the company.
        total_liabilities:
          type: number
          nullable: false
          description: The total liabilities of the company.
        current_liabilities:
          type: number
          nullable: false
          description: The current liabilities of the company.
        current_debt:
          type: number
          nullable: false
          description: The current debt of the company.
        trade_and_non_trade_payables:
          type: number
          nullable: false
          description: The trade and non-trade payables of the company.
        deferred_revenue:
          type: number
          nullable: false
          description: The deferred revenue of the company.
        deposit_liabilities:
          type: number
          nullable: false
          description: The deposit liabilities of the company.
        non_current_liabilities:
          type: number
          nullable: false
          description: The non-current liabilities of the company.
        non_current_debt:
          type: number
          nullable: false
          description: The non-current debt of the company.
        tax_liabilities:
          type: number
          nullable: false
          description: The tax liabilities of the company.
        shareholders_equity:
          type: number
          nullable: false
          description: The shareholders' equity of the company.
        retained_earnings:
          type: number
          nullable: false
          description: The retained earnings of the company.
        accumulated_other_comprehensive_income:
          type: number
          nullable: false
          description: The accumulated other comprehensive income of the company.
        total_debt:
          type: number
          nullable: false
          description: The total debt of the company.
    BalanceSheetResponse:
      type: object
      properties:
        balance_sheets:
          type: array
          items:
            $ref: '#/components/schemas/BalanceSheet'
    BalanceSheetSegments:
      allOf:
        - $ref: '#/components/schemas/SegmentMetadata'
        - type: object
          properties:
            assets:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Assets broken down by segment.
            goodwill:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Goodwill broken down by segment.
            long_lived_assets:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Long-lived assets broken down by segment.
    BalanceSheetSegmentsResponse:
      type: object
      properties:
        segmented_financials:
          type: array
          items:
            $ref: '#/components/schemas/BalanceSheetSegments'
    BatchUserInfoResponse:
      type: object
      properties:
        users:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              userName:
                type: string
              url:
                type: string
              id:
                type: string
              name:
                type: string
              isBlueVerified:
                type: boolean
              verifiedType:
                type: string
              profilePicture:
                type: string
              coverPicture:
                type: string
              description:
                type: string
              location:
                type: string
              followers:
                type: integer
              following:
                type: integer
              canDm:
                type: boolean
              createdAt:
                type: string
              favouritesCount:
                type: integer
              hasCustomTimelines:
                type: boolean
              isTranslator:
                type: boolean
              mediaCount:
                type: integer
              statusesCount:
                type: integer
              withheldInCountries:
                type: array
                items:
                  type: string
              possiblySensitive:
                type: boolean
              pinnedTweetIds:
                type: array
                items:
                  type: string
              isAutomated:
                type: boolean
              automatedBy:
                type: string
              unavailable:
                type: boolean
              message:
                type: string
              unavailableReason:
                type: string
        status:
          type: string
          enum:
            - success
            - error
        msg:
          type: string
    Beta:
      type: object
      properties:
        value:
          type: number
          nullable: true
          description: Beta coefficient of stock monthly returns vs benchmark monthly returns.
        ticker:
          type: string
          description: The requested ticker symbol.
        benchmark:
          type: string
          description: Benchmark ticker used for beta calculation.
        requested_lookback:
          type: string
          description: Requested lookback window.
        interval:
          type: string
          description: Interval used for returns alignment.
        start_date:
          type: string
          format: date
          nullable: true
          description: First aligned month-end date used.
        end_date:
          type: string
          format: date
          nullable: true
          description: Last aligned month-end date used.
        n_observations:
          type: integer
          description: Number of overlapping monthly observations used.
        r_squared:
          type: number
          nullable: true
          description: Coefficient of determination for the OLS fit.
        method:
          type: string
          description: Computation method used.
        price_type:
          type: string
          description: Price type used to compute returns.
        reason:
          type: string
          nullable: true
          description: Present when value is null due to insufficient or invalid input data.
    BetaResponse:
      type: object
      properties:
        beta:
          $ref: '#/components/schemas/Beta'
    CashFlowStatement:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol.
        report_period:
          type: string
          format: date
          description: The reporting period of the cash flow statement.
        fiscal_period:
          type: string
          description: The fiscal period of the cash flow statement.
        period:
          type: string
          enum:
            - quarterly
            - ttm
            - annual
          description: The time period of the cash flow statement.
        currency:
          type: string
          description: The currency in which the financial data is reported.
        net_income:
          type: number
          nullable: false
          description: The net income of the company.
        depreciation_and_amortization:
          type: number
          nullable: false
          description: The depreciation and amortization of the company.
        share_based_compensation:
          type: number
          nullable: false
          description: The share-based compensation of the company.
        net_cash_flow_from_operations:
          type: number
          nullable: false
          description: The net cash flow from operations of the company.
        capital_expenditure:
          type: number
          nullable: false
          description: The capital expenditure of the company.
        business_acquisitions_and_disposals:
          type: number
          nullable: false
          description: The business acquisitions and disposals of the company.
        investment_acquisitions_and_disposals:
          type: number
          nullable: false
          description: The investment acquisitions and disposals of the company.
        net_cash_flow_from_investing:
          type: number
          nullable: false
          description: The net cash flow from investing of the company.
        issuance_or_repayment_of_debt_securities:
          type: number
          nullable: false
          description: The issuance or repayment of debt securities of the company.
        issuance_or_purchase_of_equity_shares:
          type: number
          nullable: false
          description: The issuance or purchase of equity shares of the company.
        dividends_and_other_cash_distributions:
          type: number
          nullable: false
          description: The dividends and other cash distributions of the company.
        net_cash_flow_from_financing:
          type: number
          nullable: false
          description: The net cash flow from financing of the company.
        change_in_cash_and_equivalents:
          type: number
          nullable: false
          description: The change in cash and equivalents of the company.
        effect_of_exchange_rate_changes:
          type: number
          nullable: false
          description: The effect of exchange rate changes of the company.
        ending_cash_balance:
          type: number
          nullable: false
          description: The ending cash balance of the company.
        free_cash_flow:
          type: number
          nullable: false
          description: The free cash flow of the company.
    CashFlowStatementResponse:
      type: object
      properties:
        cash_flow_statements:
          type: array
          items:
            $ref: '#/components/schemas/CashFlowStatement'
    CashFlowStatementSegments:
      allOf:
        - $ref: '#/components/schemas/SegmentMetadata'
        - type: object
          properties:
            capital_expenditure:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Capital expenditure broken down by segment.
    CashFlowStatementSegmentsResponse:
      type: object
      properties:
        segmented_financials:
          type: array
          items:
            $ref: '#/components/schemas/CashFlowStatementSegments'
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: The Sonar model to use.
          enum:
            - sonar
            - sonar-pro
            - sonar-reasoning-pro
            - sonar-deep-research
        messages:
          type: array
          description: A list of messages comprising the conversation so far.
          items:
            type: object
            required:
              - role
              - content
            properties:
              role:
                type: string
                enum:
                  - system
                  - user
                  - assistant
                description: The role of the message author.
              content:
                type: string
                description: The content of the message.
        max_tokens:
          type: integer
          description: The maximum number of tokens to generate in the response.
        temperature:
          type: number
          description: Sampling temperature between 0 and 2. Lower values make output more focused and deterministic.
          default: 0.2
          minimum: 0
          maximum: 2
        top_p:
          type: number
          description: Nucleus sampling parameter. The model considers tokens with top_p probability mass.
          default: 0.9
          minimum: 0
          maximum: 1
        top_k:
          type: integer
          description: The number of tokens to keep for top-k filtering.
          default: 0
          minimum: 0
          maximum: 2048
        stream:
          type: boolean
          description: Whether to stream the response using server-sent events.
          default: false
        search_context:
          type: string
          description: Controls how much search context to use. Affects per-request cost.
          enum:
            - low
            - medium
            - high
          default: low
        frequency_penalty:
          type: number
          description: >-
            Penalizes new tokens based on their existing frequency in the text so far. Positive values decrease the
            likelihood of repeating the same line verbatim.
          default: 1
          minimum: 0
          maximum: 2
        presence_penalty:
          type: number
          description: >-
            Penalizes new tokens based on whether they appear in the text so far. Positive values increase the
            likelihood of talking about new topics.
          default: 0
          minimum: -2
          maximum: 2
        return_citations:
          type: boolean
          description: Whether to return citations and search results in the response.
          default: true
        search_recency_filter:
          type: string
          description: Filter search results by recency.
          enum:
            - month
            - week
            - day
            - hour
        search_domain_filter:
          type: array
          description: Limit search to specific domains.
          items:
            type: string
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the completion.
        model:
          type: string
          description: The model used for the completion.
        object:
          type: string
          example: chat.completion
        created:
          type: integer
          description: Unix timestamp of when the completion was created.
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
                    description: The AI-generated answer, with inline citation references like [1][2].
              finish_reason:
                type: string
                enum:
                  - stop
                  - length
        citations:
          type: array
          description: List of source URLs referenced in the answer.
          items:
            type: string
        search_results:
          type: array
          description: Detailed search results with titles, snippets, and URLs.
          items:
            type: object
            properties:
              title:
                type: string
              url:
                type: string
              snippet:
                type: string
              date:
                type: string
              source:
                type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
            search_context_size:
              type: string
    CiksResponse:
      type: object
      properties:
        resource:
          type: string
          description: The resource type identifier.
        ciks:
          type: array
          items:
            type: string
          description: List of available CIK codes.
    CommunityInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        question:
          type: string
        member_count:
          type: integer
        moderator_count:
          type: integer
        created_at:
          type: string
        join_policy:
          type: string
        invites_policy:
          type: string
        is_nsfw:
          type: boolean
        is_pinned:
          type: boolean
        role:
          type: string
        primary_topic:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        banner_url:
          type: string
        search_tags:
          type: array
          items:
            type: string
        rules:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              description:
                type: string
        creator:
          $ref: '#/components/schemas/User'
        admin:
          $ref: '#/components/schemas/User'
        members_preview:
          type: array
          items:
            type: object
    CompanyFacts:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol of the company.
        name:
          type: string
          description: The name of the company.
        cik:
          type: string
          description: The Central Index Key (CIK) of the company.
        industry:
          type: string
          description: The industry of the company.
        sector:
          type: string
          description: The sector of the company.
        category:
          type: string
          description: The category of the company.
        exchange:
          type: string
          description: The exchange of the company.
        is_active:
          type: boolean
          description: Whether the company is currently active.
        listing_date:
          type: string
          format: date
          description: The date the company was listed on the stock exchange.
        location:
          type: string
          description: The location of the company.
        market_cap:
          type: number
          description: The market capitalization of the company.
        number_of_employees:
          type: number
          description: The number of employees at the company.
        sec_filings_url:
          type: string
          format: uri
          description: The URL of the company's SEC filings.
        sic_code:
          type: string
          description: The Standard Industrial Classification (SIC) code of the company.
        sic_industry:
          type: string
          description: The industry of the company based on the SIC code.
        sic_sector:
          type: string
          description: The sector of the company based on the SIC code.
        website_url:
          type: string
          format: uri
          description: The URL of the company's website.
        weighted_average_shares:
          type: number
          description: The weighted average shares of the company.
    CompanyFactsResponse:
      type: object
      properties:
        company_facts:
          $ref: '#/components/schemas/CompanyFacts'
    Content:
      type: object
      properties:
        parts:
          type: array
          items:
            oneOf:
              - type: object
                properties:
                  text:
                    type: string
              - type: object
                properties:
                  inline_data:
                    type: object
        role:
          type: string
          enum:
            - system
            - user
            - assistant
    CryptoPriceSnapshot:
      type: object
      properties:
        price:
          type: number
          description: The current price of the cryptocurrency.
        ticker:
          type: string
          description: The ticker symbol.
        day_change:
          type: number
          description: The price change over the last 24 hours.
        day_change_percent:
          type: number
          description: The percentage price change over the last 24 hours.
        time:
          type: string
          description: The timestamp of the price snapshot in human-readable format in UTC.
    CryptoPriceSnapshotResponse:
      type: object
      properties:
        snapshot:
          $ref: '#/components/schemas/CryptoPriceSnapshot'
    CryptoPricesResponse:
      type: object
      properties:
        prices:
          type: array
          items:
            $ref: '#/components/schemas/Price'
    Earnings:
      type: object
      properties:
        ticker:
          type: string
          description: The requested ticker symbol.
        report_period:
          type: string
          format: date
          description: Most recent report period found for the ticker.
        fiscal_period:
          type: string
          nullable: true
          description: Fiscal period label (e.g. 2025-Q4 or 2025-FY).
        currency:
          type: string
          nullable: true
          description: ISO currency code (e.g. USD).
        quarterly:
          $ref: '#/components/schemas/EarningsTimeDimension'
        annual:
          $ref: '#/components/schemas/EarningsTimeDimension'
    EarningsResponse:
      type: object
      properties:
        earnings:
          $ref: '#/components/schemas/Earnings'
    EarningsTimeDimension:
      type: object
      properties:
        fiscal_period:
          type: string
          nullable: true
          description: Fiscal period label (e.g. 2025-Q4 or 2025-FY).
        currency:
          type: string
          nullable: true
          description: ISO currency code (e.g. USD).
        revenue:
          type: number
          nullable: true
        estimated_revenue:
          type: number
          description: Estimated revenue. Returned only when available.
        revenue_surprise:
          type: string
          description: Revenue surprise classification versus estimate. Returned only when available.
          enum:
            - BEAT
            - MISS
            - MEET
        earnings_per_share:
          type: number
          nullable: true
        estimated_earnings_per_share:
          type: number
          description: Estimated earnings per share. Returned only when available.
        eps_surprise:
          type: string
          description: EPS surprise classification versus estimate. Returned only when available.
          enum:
            - BEAT
            - MISS
            - MEET
        net_income:
          type: number
          nullable: true
        gross_profit:
          type: number
          nullable: true
        operating_income:
          type: number
          nullable: true
        weighted_average_shares:
          type: number
          nullable: true
        weighted_average_shares_diluted:
          type: number
          nullable: true
        cash_and_equivalents:
          type: number
          nullable: true
        total_debt:
          type: number
          nullable: true
        total_assets:
          type: number
          nullable: true
        total_liabilities:
          type: number
          nullable: true
        shareholders_equity:
          type: number
          nullable: true
        net_cash_flow_from_operations:
          type: number
          nullable: true
        capital_expenditure:
          type: number
          nullable: true
        net_cash_flow_from_investing:
          type: number
          nullable: true
        net_cash_flow_from_financing:
          type: number
          nullable: true
        change_in_cash_and_equivalents:
          type: number
          nullable: true
        free_cash_flow:
          type: number
          nullable: true
        revenue_chg:
          type: number
          description: >-
            Percentage change in revenue. QoQ in quarterly payload and YoY in annual payload. Returned only when
            calculable.
        net_income_chg:
          type: number
          description: >-
            Percentage change in net income. QoQ in quarterly payload and YoY in annual payload. Returned only when
            calculable.
        operating_income_chg:
          type: number
          description: >-
            Percentage change in operating income. QoQ in quarterly payload and YoY in annual payload. Returned only
            when calculable.
        gross_profit_chg:
          type: number
          description: >-
            Percentage change in gross profit. QoQ in quarterly payload and YoY in annual payload. Returned only when
            calculable.
        net_cash_flow_from_operations_chg:
          type: number
          description: >-
            Percentage change in net cash flow from operations. QoQ in quarterly payload and YoY in annual payload.
            Returned only when calculable.
        net_cash_flow_from_investing_chg:
          type: number
          description: >-
            Percentage change in net cash flow from investing. QoQ in quarterly payload and YoY in annual payload.
            Returned only when calculable.
        net_cash_flow_from_financing_chg:
          type: number
          description: >-
            Percentage change in net cash flow from financing. QoQ in quarterly payload and YoY in annual payload.
            Returned only when calculable.
        free_cash_flow_chg:
          type: number
          description: >-
            Percentage change in free cash flow. QoQ in quarterly payload and YoY in annual payload. Returned only when
            calculable.
    Entities:
      type: object
      properties:
        hashtags:
          type: array
          items:
            type: object
            properties:
              indices:
                type: array
                items:
                  type: integer
              text:
                type: string
        urls:
          type: array
          items:
            type: object
            properties:
              display_url:
                type: string
              expanded_url:
                type: string
              indices:
                type: array
                items:
                  type: integer
              url:
                type: string
        user_mentions:
          type: array
          items:
            type: object
            properties:
              id_str:
                type: string
              name:
                type: string
              screen_name:
                type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A short error message.
        message:
          type: string
          description: A more detailed error message.
    Exhibit:
      type: object
      properties:
        number:
          type: string
          description: The exhibit number (e.g., '99.1').
        description:
          type: string
          description: The description of the exhibit.
        url:
          type: string
          format: uri
          description: The URL to the exhibit document on the SEC website.
        text:
          type: string
          description: The raw text content of the exhibit. Only included when 'include_exhibits' parameter is set to true.
    ExplainSearchRequest:
      type: object
      required:
        - search_id
      properties:
        search_id:
          type: string
          description: ID of the search to explain
        response_mode:
          type: string
          enum:
            - COMPLETE
            - SUMMARY
            - BULLET_POINTS
          default: COMPLETE
          description: Format of the explanation response
        language:
          type: string
          default: en
          description: Language code for the explanation (e.g., en, zh, ar)
          example: ar
        detail_level:
          type: string
          enum:
            - BRIEF
            - MODERATE
            - DETAILED
          default: MODERATE
          description: Level of detail in the explanation
    ExplainSearchResponse:
      type: object
      required:
        - search_id
        - explanation
      properties:
        search_id:
          type: string
          description: ID of the search being explained
        explanation:
          type: string
          description: Detailed explanation of the search results
        language:
          type: string
          description: Language of the explanation
        response_mode:
          type: string
          description: Format of the response
        summary:
          type: string
          description: Brief summary of the explanation
        key_insights:
          type: array
          items:
            type: string
          description: List of key insights from the search results
        confidence_score:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence score for the explanation
        generated_at:
          type: string
          format: date-time
          description: Timestamp when the explanation was generated
    Filing:
      type: object
      properties:
        cik:
          type: integer
          description: The Central Index Key (CIK) of the company.
        accession_number:
          type: string
          description: The accession number of the filing.
        filing_type:
          type: string
          description: The type of the SEC filing (e.g., 10-Q, 8-K).
        report_date:
          type: string
          format: date
          description: The date of the report.
        ticker:
          type: string
          description: The ticker symbol.
        url:
          type: string
          format: uri
          description: The URL of the SEC filing.
    FilingItem:
      type: object
      properties:
        number:
          type: string
          description: The item number.
        name:
          type: string
          description: The item name.
        text:
          type: string
          description: The item text.
    FilingItemsResponse:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol of the company.
        cik:
          type: string
          description: The Central Index Key (CIK) of the company.
        filing_type:
          type: string
          description: The type of filing.
        accession_number:
          type: string
          description: The accession number of the filing.
        year:
          type: integer
          description: The year of the filing.
        quarter:
          type: integer
          description: The quarter of the filing.
        items:
          type: array
          items:
            $ref: '#/components/schemas/FilingItem'
    FilingsResponse:
      type: object
      properties:
        filings:
          type: array
          items:
            $ref: '#/components/schemas/Filing'
    FinancialMetricSnapshot:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol of the company.
        market_cap:
          type: number
          nullable: true
          description: The total market capitalization (stock price × shares outstanding).
        enterprise_value:
          type: number
          nullable: true
          description: The total value of the company (market cap + debt - cash).
        price_to_earnings_ratio:
          type: number
          nullable: true
          description: Price to earnings ratio.
        price_to_book_ratio:
          type: number
          nullable: true
          description: Price to book ratio.
        price_to_sales_ratio:
          type: number
          nullable: true
          description: Price to sales ratio.
        enterprise_value_to_ebitda_ratio:
          type: number
          nullable: true
          description: Enterprise value to EBITDA ratio.
        enterprise_value_to_revenue_ratio:
          type: number
          nullable: true
          description: Enterprise value to revenue ratio.
        free_cash_flow_yield:
          type: number
          nullable: true
          description: Free cash flow yield.
        peg_ratio:
          type: number
          nullable: true
          description: Price to earnings growth ratio.
        gross_margin:
          type: number
          nullable: true
          description: Gross profit as a percentage of revenue.
        operating_margin:
          type: number
          nullable: true
          description: Operating income as a percentage of revenue.
        net_margin:
          type: number
          nullable: true
          description: Net income as a percentage of revenue.
        return_on_equity:
          type: number
          nullable: true
          description: Net income as a percentage of shareholders' equity.
        return_on_assets:
          type: number
          nullable: true
          description: Net income as a percentage of total assets.
        return_on_invested_capital:
          type: number
          nullable: true
          description: Net operating profit after taxes as a percentage of invested capital.
        asset_turnover:
          type: number
          nullable: true
          description: Revenue divided by average total assets.
        inventory_turnover:
          type: number
          nullable: true
          description: Cost of goods sold divided by average inventory.
        receivables_turnover:
          type: number
          nullable: true
          description: Revenue divided by average accounts receivable.
        days_sales_outstanding:
          type: number
          nullable: true
          description: Average accounts receivable divided by revenue over the period.
        operating_cycle:
          type: number
          nullable: true
          description: Inventory turnover + receivables turnover.
        working_capital_turnover:
          type: number
          nullable: true
          description: Revenue divided by average working capital.
        current_ratio:
          type: number
          nullable: true
          description: Current assets divided by current liabilities.
        quick_ratio:
          type: number
          nullable: true
          description: Quick assets divided by current liabilities.
        cash_ratio:
          type: number
          nullable: true
          description: Cash and cash equivalents divided by current liabilities.
        operating_cash_flow_ratio:
          type: number
          nullable: true
          description: Operating cash flow divided by current liabilities.
        debt_to_equity:
          type: number
          nullable: true
          description: Total debt divided by shareholders' equity.
        debt_to_assets:
          type: number
          nullable: true
          description: Total debt divided by total assets.
        interest_coverage:
          type: number
          nullable: true
          description: EBIT divided by interest expense.
        revenue_growth:
          type: number
          nullable: true
          description: Year-over-year growth in revenue.
        earnings_growth:
          type: number
          nullable: true
          description: Year-over-year growth in earnings.
        book_value_growth:
          type: number
          nullable: true
          description: Year-over-year growth in book value.
        earnings_per_share_growth:
          type: number
          nullable: true
          description: Growth in earnings per share over the period.
        free_cash_flow_growth:
          type: number
          nullable: true
          description: Growth in free cash flow over the period.
        operating_income_growth:
          type: number
          nullable: true
          description: Growth in operating income over the period.
        ebitda_growth:
          type: number
          nullable: true
          description: Growth in EBITDA over the period.
        payout_ratio:
          type: number
          nullable: true
          description: Dividends paid as a percentage of net income.
        earnings_per_share:
          type: number
          nullable: true
          description: Net income divided by weighted average shares outstanding.
        book_value_per_share:
          type: number
          nullable: true
          description: Shareholders' equity divided by shares outstanding.
        free_cash_flow_per_share:
          type: number
          nullable: true
          description: Free cash flow divided by shares outstanding.
    FinancialMetricSnapshotResponse:
      type: object
      properties:
        snapshot:
          $ref: '#/components/schemas/FinancialMetricSnapshot'
    FinancialMetricsResponse:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol of the company.
        market_cap:
          type: number
          description: The market capitalization of the company.
        enterprise_value:
          type: number
          description: The total value of the company (market cap + debt - cash).
        price_to_earnings_ratio:
          type: number
          description: Price to earnings ratio.
        price_to_book_ratio:
          type: number
          description: Price to book ratio.
        price_to_sales_ratio:
          type: number
          description: Price to sales ratio.
        enterprise_value_to_ebitda_ratio:
          type: number
          description: Enterprise value to EBITDA ratio.
        enterprise_value_to_revenue_ratio:
          type: number
          description: Enterprise value to revenue ratio.
        free_cash_flow_yield:
          type: number
          description: Free cash flow yield.
        peg_ratio:
          type: number
          description: Price to earnings growth ratio.
        gross_margin:
          type: number
          description: Gross profit as a percentage of revenue.
        operating_margin:
          type: number
          description: Operating income as a percentage of revenue.
        net_margin:
          type: number
          description: Net income as a percentage of revenue.
        return_on_equity:
          type: number
          description: Net income as a percentage of shareholders' equity.
        return_on_assets:
          type: number
          description: Net income as a percentage of total assets.
        return_on_invested_capital:
          type: number
          description: Net operating profit after taxes as a percentage of invested capital.
        asset_turnover:
          type: number
          description: Revenue divided by average total assets.
        inventory_turnover:
          type: number
          description: Cost of goods sold divided by average inventory.
        receivables_turnover:
          type: number
          description: Revenue divided by average accounts receivable.
        days_sales_outstanding:
          type: number
          description: Average accounts receivable divided by revenue over the period.
        operating_cycle:
          type: number
          description: Inventory turnover + receivables turnover.
        working_capital_turnover:
          type: number
          description: Revenue divided by average working capital.
        current_ratio:
          type: number
          description: Current assets divided by current liabilities.
        quick_ratio:
          type: number
          description: Quick assets divided by current liabilities.
        cash_ratio:
          type: number
          description: Cash and cash equivalents divided by current liabilities.
        operating_cash_flow_ratio:
          type: number
          description: Operating cash flow divided by current liabilities.
        debt_to_equity:
          type: number
          description: Total debt divided by shareholders' equity.
        debt_to_assets:
          type: number
          description: Total debt divided by total assets.
        interest_coverage:
          type: number
          description: EBIT divided by interest expense.
        revenue_growth:
          type: number
          description: Year-over-year growth in revenue.
        earnings_growth:
          type: number
          description: Year-over-year growth in earnings.
        book_value_growth:
          type: number
          description: Year-over-year growth in book value.
        earnings_per_share_growth:
          type: number
          description: Growth in earnings per share over the period.
        free_cash_flow_growth:
          type: number
          description: Growth in free cash flow over the period.
        operating_income_growth:
          type: number
          description: Growth in operating income over the period.
        ebitda_growth:
          type: number
          description: Growth in EBITDA over the period.
        payout_ratio:
          type: number
          description: Dividends paid as a percentage of net income.
        earnings_per_share:
          type: number
          description: Net income divided by weighted average shares outstanding.
        book_value_per_share:
          type: number
          description: Shareholders' equity divided by shares outstanding.
        free_cash_flow_per_share:
          type: number
          description: Free cash flow divided by shares outstanding.
    FinancialsResponse:
      type: object
      properties:
        financials:
          type: object
          properties:
            income_statements:
              type: array
              items:
                $ref: '#/components/schemas/IncomeStatement'
            balance_sheets:
              type: array
              items:
                $ref: '#/components/schemas/BalanceSheet'
            cash_flow_statements:
              type: array
              items:
                $ref: '#/components/schemas/CashFlowStatement'
    FinancialsSearchResponse:
      type: object
      properties:
        search_results:
          type: array
          items:
            type: object
            properties:
              ticker:
                type: string
                description: The ticker symbol of the company.
              report_period:
                type: string
                format: date
                description: The reporting period of the financial data.
              period:
                type: string
                enum:
                  - annual
                  - quarterly
                  - ttm
                description: The time period of the financial data.
              currency:
                type: string
                description: The currency of the financial data.
            additionalProperties:
              type: string
              description: Additional financial metrics based on the search criteria.
    FollowRelationshipResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            following:
              type: boolean
            followed_by:
              type: boolean
        status:
          type: string
          enum:
            - success
            - error
        message:
          type: string
    GenerateContentRequest:
      type: object
      properties:
        contents:
          type: array
          items:
            $ref: '#/components/schemas/Content'
          description: Content of the conversation, required
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
          description: Optional tools the model can use
        toolConfig:
          type: object
          description: Optional tool configuration
        safetySettings:
          type: array
          items:
            $ref: '#/components/schemas/SafetySetting'
        systemInstruction:
          $ref: '#/components/schemas/Content'
        generationConfig:
          $ref: '#/components/schemas/GenerationConfig'
        cachedContent:
          type: string
          description: Optional cached content ID
      required:
        - contents
    GenerateContentResponse:
      type: object
      properties:
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/Content'
    GenerationConfig:
      type: object
    IncomeStatement:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol.
        report_period:
          type: string
          format: date
          description: The reporting period of the income statement.
        fiscal_period:
          type: string
          description: The fiscal period of the income statement.
        period:
          type: string
          enum:
            - quarterly
            - ttm
            - annual
          description: The time period of the income statement.
        currency:
          type: string
          description: The currency in which the financial data is reported.
        revenue:
          type: number
          nullable: false
          description: The total revenue of the company.
        cost_of_revenue:
          type: number
          nullable: false
          description: The cost of revenue of the company.
        gross_profit:
          type: number
          nullable: false
          description: The gross profit of the company.
        operating_expense:
          type: number
          nullable: false
          description: The operating expenses of the company.
        selling_general_and_administrative_expenses:
          type: number
          nullable: false
          description: The selling, general, and administrative expenses of the company.
        research_and_development:
          type: number
          nullable: false
          description: The research and development expenses of the company.
        operating_income:
          type: number
          nullable: false
          description: The operating income of the company.
        interest_expense:
          type: number
          nullable: false
          description: The interest expenses of the company.
        ebit:
          type: number
          nullable: false
          description: The earnings before interest and taxes of the company.
        income_tax_expense:
          type: number
          nullable: false
          description: The income tax expenses of the company.
        net_income_discontinued_operations:
          type: number
          nullable: false
          description: The net income from discontinued operations of the company.
        net_income_non_controlling_interests:
          type: number
          nullable: false
          description: The net income from non-controlling interests of the company.
        net_income:
          type: number
          nullable: false
          description: The net income of the company.
        net_income_common_stock:
          type: number
          nullable: false
          description: The net income available to common stockholders of the company.
        preferred_dividends_impact:
          type: number
          nullable: false
          description: The impact of preferred dividends on the net income of the company.
        consolidated_income:
          type: number
          nullable: false
          description: The consolidated income of the company.
        earnings_per_share:
          type: number
          nullable: false
          description: The earnings per share of the company.
        earnings_per_share_diluted:
          type: number
          nullable: false
          description: The diluted earnings per share of the company.
        dividends_per_common_share:
          type: number
          nullable: false
          description: The dividends per common share of the company.
        weighted_average_shares:
          type: number
          nullable: false
          description: The weighted average shares of the company.
        weighted_average_shares_diluted:
          type: number
          nullable: false
          description: The diluted weighted average shares of the company.
    IncomeStatementResponse:
      type: object
      properties:
        income_statements:
          type: array
          items:
            $ref: '#/components/schemas/IncomeStatement'
    IncomeStatementSegments:
      allOf:
        - $ref: '#/components/schemas/SegmentMetadata'
        - type: object
          properties:
            revenue:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Revenue broken down by product and/or segment.
            operating_income:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Operating income broken down by segment.
            depreciation:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Depreciation broken down by segment.
    IncomeStatementSegmentsResponse:
      type: object
      properties:
        segmented_financials:
          type: array
          items:
            $ref: '#/components/schemas/IncomeStatementSegments'
    InsiderTrade:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol of the company.
        issuer:
          type: string
          description: The name of the issuing company.
        name:
          type: string
          description: The name of the insider.
        title:
          type: string
          description: The title of the insider.
        is_board_director:
          type: boolean
          description: Whether the insider is a board director.
        transaction_date:
          type: string
          format: date
          description: The date of the transaction.
        transaction_shares:
          type: number
          description: The number of shares involved in the transaction.
        transaction_price_per_share:
          type: number
          description: The price per share in the transaction.
        transaction_value:
          type: number
          description: The total value of the transaction.
        shares_owned_before_transaction:
          type: number
          description: The number of shares owned before the transaction.
        shares_owned_after_transaction:
          type: number
          description: The number of shares owned after the transaction.
        security_title:
          type: string
          description: The title of the security involved in the transaction.
        filing_date:
          type: string
          format: date
          description: The date the transaction was filed.
    InsiderTradesResponse:
      type: object
      properties:
        insider_trades:
          type: array
          items:
            $ref: '#/components/schemas/InsiderTrade'
    InstitutionalOwnership:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol, if queried by investor.
        investor:
          type: string
          description: The investor name, if queried by ticker.
        report_period:
          type: string
          format: date
          description: The reporting period of the institutional ownership.
        price:
          type: number
          description: The estimated purchase price of the equity position.
        shares:
          type: number
          description: The number of shares held by the investment manager.
        market_value:
          type: number
          description: The market value of the equity position.
    InstitutionalOwnershipResponse:
      type: object
      properties:
        institutional-ownership:
          type: array
          items:
            $ref: '#/components/schemas/InstitutionalOwnership'
    InterestRate:
      type: object
      properties:
        bank:
          type: string
          description: The symbol of the central bank.
        name:
          type: string
          description: The name of the central bank.
        rate:
          type: number
          description: The interest rate of the central bank.
        date:
          type: string
          description: The date of the interest rate in YYYY-MM-DD format.
    InterestRatesResponse:
      type: object
      properties:
        interest_rates:
          type: array
          items:
            $ref: '#/components/schemas/InterestRate'
    KPIGuidanceItem:
      type: object
      required:
        - ticker
        - metric_name
        - period
        - period_type
      properties:
        ticker:
          type: string
          example: DAL
        metric_name:
          type: string
          example: Operating Margin
        value:
          type: number
          nullable: true
        unit:
          type: string
          example: '%'
        period:
          type: string
          example: Q2 2026
        period_type:
          type: string
          enum:
            - quarterly
            - annual
        segment:
          type: string
          nullable: true
        low:
          type: number
          nullable: true
          description: Low end of guidance range.
          example: 6
        high:
          type: number
          nullable: true
          description: High end of guidance range.
          example: 8
        point_estimate:
          type: number
          nullable: true
          description: Single-point guidance when no range is given.
        prior_value:
          type: number
          nullable: true
          description: Prior guidance value for revisions.
        raw_text:
          type: string
          nullable: true
          description: Original guidance text from the filing.
        change_direction:
          type: string
          nullable: true
          description: 'Direction: raised, lowered, maintained, initiated, withdrawn.'
          example: initiated
        source_text:
          type: string
          nullable: true
        source_url:
          type: string
          format: uri
          nullable: true
    KPIGuidanceResponse:
      type: object
      properties:
        kpi_guidance:
          type: array
          items:
            $ref: '#/components/schemas/KPIGuidanceItem'
    KPIMetric:
      type: object
      required:
        - ticker
        - metric_name
        - value
        - unit
        - period
        - period_type
      properties:
        ticker:
          type: string
          description: Stock ticker symbol.
          example: DAL
        metric_name:
          type: string
          description: Canonical metric name.
          example: load_factor
        value:
          type: number
          nullable: true
          description: Extracted numeric value.
          example: 82
        unit:
          type: string
          description: Unit of measure (e.g., %, cents, dollars, miles, count).
          example: '%'
        period:
          type: string
          description: Reporting period (e.g., Q4 2025, FY 2025, or a date like 2025-04-30 for non-standard fiscal years).
          example: Q4 2025
        period_type:
          type: string
          enum:
            - quarterly
            - annual
          description: Whether this is a quarterly or annual figure.
          example: quarterly
        segment:
          type: string
          nullable: true
          description: >-
            Business segment, geography, or sub-category. Only present when the metric is reported for a sub-unit rather
            than the consolidated entity.
          example: Commercial Engines & Services
        yoy_value:
          type: number
          nullable: true
          description: Year-over-year comparison value from the prior period.
          example: 84
        yoy_change_pct:
          type: number
          nullable: true
          description: Year-over-year percentage change.
          example: -2.381
        source_text:
          type: string
          nullable: true
          description: The source text span from the filing where this value was found.
          example: Passenger load factor
        source_url:
          type: string
          format: uri
          description: >-
            Direct link to the SEC filing. When available, includes a text fragment that highlights the source in the
            browser.
          example: https://www.sec.gov/Archives/edgar/data/27904/000002790426000008/deltaairlinesannouncesdece.htm
    KPIMetricsResponse:
      type: object
      properties:
        kpi_metrics:
          type: array
          items:
            $ref: '#/components/schemas/KPIMetric'
    KPINonGAAPMetric:
      type: object
      required:
        - ticker
        - metric_name
        - value
        - unit
        - period
        - period_type
      properties:
        ticker:
          type: string
          example: DAL
        metric_name:
          type: string
          example: Adjusted Diluted EPS
        value:
          type: number
          nullable: true
          example: 0.64
        unit:
          type: string
          example: USD per share
        period:
          type: string
          example: Q1 2026
        period_type:
          type: string
          enum:
            - quarterly
            - annual
        gaap_equivalent:
          type: string
          nullable: true
          description: The GAAP line item this metric adjusts.
          example: Diluted earnings per share
        key_adjustments:
          type: string
          nullable: true
          description: Description of adjustments made.
          example: Excludes restructuring charges of $150M
        source_text:
          type: string
          nullable: true
        source_url:
          type: string
          format: uri
          nullable: true
    KPINonGAAPResponse:
      type: object
      properties:
        kpi_non_gaap:
          type: array
          items:
            $ref: '#/components/schemas/KPINonGAAPMetric'
    MyInfoResponse:
      type: object
      properties:
        recharge_credits:
          type: integer
    News:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol.
        title:
          type: string
          description: The title of the news article.
        author:
          type: string
          description: The author of the news article.
        source:
          type: string
          description: The source of the news article.
        date:
          type: string
          format: date
          description: The date the news article was published.
        url:
          type: string
          format: uri
          description: The URL of the news article.
        sentiment:
          type: string
          description: The sentiment of the news article.
    NewsResponse:
      type: object
      properties:
        news:
          type: array
          items:
            $ref: '#/components/schemas/News'
    PressRelease:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol of the company.
        title:
          type: string
          description: The title of the press release.
        url:
          type: string
          format: uri
          description: The URL of the press release.
        date:
          type: string
          format: date
          description: The date the press release was published.
        text:
          type: string
          description: The full text of the press release.
    PressReleasesResponse:
      type: object
      properties:
        press_releases:
          type: array
          items:
            $ref: '#/components/schemas/PressRelease'
    Price:
      type: object
      properties:
        open:
          type: number
          description: The open price of the ticker in the given time period.
        close:
          type: number
          description: The close price of the ticker in the given time period.
        high:
          type: number
          description: The high price of the ticker in the given time period.
        low:
          type: number
          description: The low price of the ticker in the given time period.
        volume:
          type: integer
          format: number
          description: The volume of the ticker in the given time period.
        time:
          type: string
          description: The human-readable time format of the price in UTC.
        time_milliseconds:
          type: number
          description: The timestamp of the price in milliseconds since epoch.
    PriceSnapshot:
      type: object
      properties:
        price:
          type: number
          description: The current price of the stock.
        ticker:
          type: string
          description: The ticker symbol.
        day_change:
          type: number
          description: The price change since the previous trading day's close.
        day_change_percent:
          type: number
          description: The percentage price change since the previous trading day's close.
        market_cap:
          type: number
          description: The market capitalization of the company.
        time:
          type: string
          description: The timestamp of the price snapshot in human-readable format in UTC.
        time_milliseconds:
          type: number
          description: The timestamp of the price snapshot in milliseconds since epoch.
    PriceSnapshotMarketResponse:
      type: object
      properties:
        snapshots:
          type: array
          items:
            $ref: '#/components/schemas/PriceSnapshot'
    PriceSnapshotResponse:
      type: object
      properties:
        snapshot:
          $ref: '#/components/schemas/PriceSnapshot'
    PricesResponse:
      type: object
      properties:
        prices:
          type: array
          items:
            $ref: '#/components/schemas/Price'
        next_page_url:
          type: string
          description: The URL to the next page of results.
    SafetySetting:
      type: object
    ScholarResult:
      type: object
      required:
        - title
        - link
        - snippet
        - authors
        - number_of_citations
      properties:
        title:
          type: string
          description: Title of the academic paper
        link:
          type: string
          format: uri
          description: URL to access the full paper
        snippet:
          type: string
          description: Brief summary or abstract of the paper
        authors:
          type: array
          items:
            type: string
          description: List of authors
        number_of_citations:
          type: integer
          minimum: 0
          description: Number of citations the paper has received
        year:
          type: integer
          description: Publication year
          minimum: 1900
          maximum: 2030
        journal:
          type: string
          description: Journal or conference name
    ScholarSearchResponse:
      type: object
      required:
        - id
        - results
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        results:
          type: array
          items:
            $ref: '#/components/schemas/ScholarResult'
          description: List of academic paper results
    SearchFiltersRequest:
      type: object
      required:
        - filters
      properties:
        period:
          type: string
          enum:
            - annual
            - quarterly
            - ttm
          default: ttm
          description: The time period for the financial data.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          description: The maximum number of results to return.
        order_by:
          type: string
          enum:
            - ticker
            - '-ticker'
            - report_period
            - '-report_period'
          default: ticker
          description: The field to order the results by.  Use -field to order in descending order.
        currency:
          type: string
          enum:
            - USD
            - EUR
            - GBP
            - JPY
            - CHF
            - AUD
            - CAD
            - SEK
          description: The currency of the financial data.
        historical:
          type: boolean
          default: false
          description: Whether to return historical financial data.
        filters:
          type: array
          items:
            type: object
            required:
              - field
              - operator
              - value
            properties:
              field:
                type: string
                description: >-
                  The criteria to filter on.  For financial metric fields, use 'gt', 'lt', 'gte', 'lte', 'eq'
                  operators.  For 'ticker' and 'cik' fields, use the 'in' operator to filter against multiple values.
              operator:
                type: string
                enum:
                  - gt
                  - lt
                  - gte
                  - lte
                  - eq
                  - in
                description: >-
                  The comparison operator. The 'in' operator can only be used with a field value of 'ticker' or 'cik'
                  and lets you filter against multiple values.
              value:
                oneOf:
                  - type: number
                    description: The value to compare against for single-value operators (gt, lt, gte, lte, eq)
                  - type: array
                    items:
                      type: string
                    description: Array of ticker or cik values to compare against when using the 'in' operator
          minItems: 1
          description: An array of filter objects to apply to the search.
    SearchLineItemsRequest:
      type: object
      required:
        - line_items
        - tickers
      properties:
        line_items:
          type: array
          items:
            type: string
            description: The financial metric to search for.
          minItems: 1
          description: An array of line items to apply to the search.
        tickers:
          type: array
          items:
            type: string
            description: The tickers to search for.
          minItems: 1
          description: An array of tickers to apply to the search.
        period:
          type: string
          enum:
            - annual
            - quarterly
            - ttm
          default: ttm
          description: The time period for the financial data.
        limit:
          type: integer
          minimum: 1
          default: 1
          description: The maximum number of results to return.
    SearchUserResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
        has_next_page:
          type: boolean
        next_cursor:
          type: string
        status:
          type: string
          enum:
            - success
            - error
        msg:
          type: string
    SegmentBreakdown:
      type: object
      properties:
        label:
          type: string
          description: The label for the segment (e.g., 'iPhone', 'Americas').
        value:
          type: number
          description: The value for the segment.
    SegmentCategory:
      type: object
      description: Segment breakdowns grouped by category.
      properties:
        product:
          type: array
          description: Breakdowns by product line.
          items:
            $ref: '#/components/schemas/SegmentBreakdown'
        segment:
          type: array
          description: Breakdowns by business or operating segment.
          items:
            $ref: '#/components/schemas/SegmentBreakdown'
    SegmentMetadata:
      type: object
      description: Common metadata fields for all segment responses.
      properties:
        ticker:
          type: string
          description: The ticker symbol.
        report_period:
          type: string
          format: date
          description: The reporting period.
        fiscal_period:
          type: string
          description: The fiscal period (e.g., Q1, Q2, Q3, Q4, FY).
        period:
          type: string
          enum:
            - quarterly
            - annual
          description: The time period.
        currency:
          type: string
          description: The reporting currency (e.g., USD, EUR, GBP).
        accession_number:
          type: string
          description: The SEC filing accession number.
        filing_url:
          type: string
          description: URL to the SEC filing.
    SegmentedFinancialsResponse:
      type: object
      properties:
        segmented_financials:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/SegmentMetadata'
              - type: object
                properties:
                  income_statement:
                    type: object
                    nullable: true
                    description: Income statement segment breakdowns for this period.
                    properties:
                      revenue:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                      operating_income:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                      depreciation:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                  balance_sheet:
                    type: object
                    nullable: true
                    description: Balance sheet segment breakdowns for this period.
                    properties:
                      assets:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                      goodwill:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                      long_lived_assets:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                  cash_flow_statement:
                    type: object
                    nullable: true
                    description: Cash flow statement segment breakdowns for this period.
                    properties:
                      capital_expenditure:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
    SegmentedRevenues:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol.
        report_period:
          type: string
          format: date
          description: The reporting period of the revenue.
        period:
          type: string
          enum:
            - quarterly
            - annual
          description: The time period of the revenue.
        items:
          type: array
          description: An array of revenue segments from SEC filings (10-Ks and 10-Qs) in XBRL format
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the revenue segment.
              amount:
                type: number
                description: >-
                  The numerical amount reported for the specified financial metric, expressed in the company's reporting
                  currency; default is USD.
              end_period:
                type: string
                format: date
                nullable: true
                description: The end period of the revenue segment.  Only provided for quarterly data.
              start_period:
                type: string
                format: date
                nullable: true
                description: The start period of the revenue segment.  Only provided for quarterly data.
              segments:
                type: array
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      description: The label for the revenue segment.
                    type:
                      type: string
                      description: The type of revenue segment.
    SegmentedRevenuesResponse:
      type: object
      properties:
        segmented_revenues:
          type: array
          items:
            $ref: '#/components/schemas/SegmentedRevenues'
    SmartResult:
      type: object
      required:
        - title
        - link
        - snippet
      properties:
        title:
          type: string
          description: Title of the result
        link:
          type: string
          format: uri
          description: URL to access the content
        snippet:
          type: string
          description: Brief summary or abstract
        authors:
          type: array
          items:
            type: string
          description: List of authors (for academic content)
        number_of_citations:
          type: integer
          minimum: 0
          description: Number of citations (for academic content)
        type:
          type: string
          enum:
            - web
            - academic
          description: Type of the result
        relevance_score:
          type: number
          minimum: 0
          maximum: 1
          description: Relevance score of the result
    SmartSearchResponse:
      type: object
      required:
        - id
        - results
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        results:
          type: array
          items:
            $ref: '#/components/schemas/SmartResult'
          description: List of smart search results combining web and academic content
        search_type:
          type: string
          enum:
            - web
            - academic
            - hybrid
          description: Type of search results included
    SpaceDetail:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        state:
          type: string
        created_at:
          type: string
          format: date-time
        scheduled_start:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        media_key:
          type: string
        is_subscribed:
          type: boolean
        settings:
          type: object
          properties:
            conversation_controls:
              type: integer
            disallow_join:
              type: boolean
            is_employee_only:
              type: boolean
            is_locked:
              type: boolean
            is_muted:
              type: boolean
            is_space_available_for_clipping:
              type: boolean
            is_space_available_for_replay:
              type: boolean
            no_incognito:
              type: boolean
            narrow_cast_space_type:
              type: integer
            max_guest_sessions:
              type: integer
            max_admin_capacity:
              type: integer
        stats:
          type: object
          properties:
            total_replay_watched:
              type: integer
            total_live_listeners:
              type: integer
            total_participants:
              type: integer
        creator:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            userName:
              type: string
            location:
              type: string
            url:
              type: string
            description:
              type: string
            protected:
              type: boolean
            isVerified:
              type: boolean
            isBlueVerified:
              type: boolean
            verifiedType:
              type: string
            followers:
              type: integer
            following:
              type: integer
            favouritesCount:
              type: integer
            statusesCount:
              type: integer
            mediaCount:
              type: integer
            createdAt:
              type: string
              format: date-time
            coverPicture:
              type: string
            profilePicture:
              type: string
            canDm:
              type: boolean
            affiliatesHighlightedLabel:
              type: object
            isAutomated:
              type: boolean
            automatedBy:
              type: string
    SpaceDetailResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SpaceDetail'
        status:
          type: string
          enum:
            - success
            - error
        msg:
          type: string
    TickersResponse:
      type: object
      properties:
        resource:
          type: string
          description: The resource type identifier.
        tickers:
          type: array
          items:
            type: string
          description: List of available ticker symbols.
    Tool:
      type: object
    Trend:
      type: object
      properties:
        name:
          type: string
        target:
          type: object
          properties:
            query:
              type: string
        rank:
          type: integer
          format: int64
        meta_description:
          type: string
    TrendsResponse:
      type: object
      properties:
        trends:
          type: array
          items:
            $ref: '#/components/schemas/Trend'
        status:
          type: string
          enum:
            - success
            - error
        msg:
          type: string
    Tweet:
      type: object
      properties:
        type:
          type: string
        id:
          type: string
        url:
          type: string
        text:
          type: string
        source:
          type: string
        retweetCount:
          type: integer
        replyCount:
          type: integer
        likeCount:
          type: integer
        quoteCount:
          type: integer
        viewCount:
          type: integer
        createdAt:
          type: string
        lang:
          type: string
        bookmarkCount:
          type: integer
        isReply:
          type: boolean
        inReplyToId:
          type: string
        conversationId:
          type: string
        displayTextRange:
          type: array
          items:
            type: integer
        inReplyToUserId:
          type: string
        inReplyToUsername:
          type: string
        author:
          $ref: '#/components/schemas/User'
        entities:
          type: object
          properties:
            hashtags:
              type: array
              items:
                type: object
                properties:
                  indices:
                    type: array
                    items:
                      type: integer
                  text:
                    type: string
            urls:
              type: array
              items:
                type: object
                properties:
                  display_url:
                    type: string
                  expanded_url:
                    type: string
                  indices:
                    type: array
                    items:
                      type: integer
                  url:
                    type: string
            user_mentions:
              type: array
              items:
                type: object
                properties:
                  id_str:
                    type: string
                  name:
                    type: string
                  screen_name:
                    type: string
        quoted_tweet:
          type: string
        retweeted_tweet:
          type: string
        isLimitedReply:
          type: boolean
    TweetThreadContextResponse:
      type: object
      properties:
        replies:
          type: array
          items:
            $ref: '#/components/schemas/Tweet'
        has_next_page:
          type: boolean
        next_cursor:
          type: string
        status:
          type: string
          enum:
            - success
            - error
        message:
          type: string
    TwitterListFollowersResponse:
      type: object
      properties:
        followers:
          type: array
          items:
            $ref: '#/components/schemas/TwitterUser'
        has_next_page:
          type: boolean
          description: Indicates if there are more results available
        next_cursor:
          type: string
          description: Cursor for fetching the next page of results
        status:
          type: string
          enum:
            - success
            - error
          description: Status of the request
        msg:
          type: string
          description: Message of the request, error message if status is error
    TwitterListMembersResponse:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/TwitterUser'
        has_next_page:
          type: boolean
          description: Indicates if there are more results available
        next_cursor:
          type: string
          description: Cursor for fetching the next page of results
        status:
          type: string
          enum:
            - success
            - error
          description: Status of the request
        msg:
          type: string
          description: Message of the request, error message if status is error
    TwitterUrl:
      type: object
      properties:
        display_url:
          type: string
          description: Display URL
        expanded_url:
          type: string
          description: Expanded URL
        indices:
          type: array
          items:
            type: integer
          description: Indices of the URL
        url:
          type: string
          description: URL
    TwitterUser:
      type: object
      properties:
        type:
          type: string
          description: Type of the user
        userName:
          type: string
          description: Username of the user
        url:
          type: string
          description: URL of the user's profile
        id:
          type: string
          description: ID of the user
        name:
          type: string
          description: Name of the user
        isBlueVerified:
          type: boolean
          description: Indicates if the user is blue verified
        verifiedType:
          type: string
          description: Type of verification
        profilePicture:
          type: string
          description: URL of the profile picture
        coverPicture:
          type: string
          description: URL of the cover picture
        description:
          type: string
          description: Description of the user
        location:
          type: string
          description: Location of the user
        followers:
          type: integer
          description: Number of followers
        following:
          type: integer
          description: Number of followings
        canDm:
          type: boolean
          description: Indicates if the user can be direct messaged
        createdAt:
          type: string
          description: Account creation date
        favouritesCount:
          type: integer
          description: Number of favorites
        hasCustomTimelines:
          type: boolean
          description: Indicates if the user has custom timelines
        isTranslator:
          type: boolean
          description: Indicates if the user is a translator
        mediaCount:
          type: integer
          description: Number of media items
        statusesCount:
          type: integer
          description: Number of statuses
        withheldInCountries:
          type: array
          items:
            type: string
          description: List of countries where the user is withheld
        possiblySensitive:
          type: boolean
          description: Indicates if the user has sensitive content
        pinnedTweetIds:
          type: array
          items:
            type: string
          description: List of pinned tweet IDs
        isAutomated:
          type: boolean
          description: Indicates if the account is automated
        automatedBy:
          type: string
          description: Indicates who automated the account
        unavailable:
          type: boolean
          description: Indicates if the account is unavailable
        message:
          type: string
          description: Message about the account
        unavailableReason:
          type: string
          description: Reason for unavailability
        profile_bio:
          type: object
          properties:
            description:
              type: string
              description: Bio description
            entities:
              type: object
              properties:
                description:
                  type: object
                  properties:
                    urls:
                      type: array
                      items:
                        $ref: '#/components/schemas/TwitterUrl'
                url:
                  type: object
                  properties:
                    urls:
                      type: array
                      items:
                        $ref: '#/components/schemas/TwitterUrl'
    User:
      type: object
      properties:
        type:
          type: string
        userName:
          type: string
        url:
          type: string
        id:
          type: string
        name:
          type: string
        isBlueVerified:
          type: boolean
        verifiedType:
          type: string
        profilePicture:
          type: string
        coverPicture:
          type: string
        description:
          type: string
        location:
          type: string
        followers:
          type: integer
        following:
          type: integer
        canDm:
          type: boolean
        createdAt:
          type: string
        favouritesCount:
          type: integer
        hasCustomTimelines:
          type: boolean
        isTranslator:
          type: boolean
        mediaCount:
          type: integer
        statusesCount:
          type: integer
        withheldInCountries:
          type: array
          items:
            type: string
        possiblySensitive:
          type: boolean
        pinnedTweetIds:
          type: array
          items:
            type: string
        isAutomated:
          type: boolean
        automatedBy:
          type: string
        unavailable:
          type: boolean
        message:
          type: string
        unavailableReason:
          type: string
        profile_bio:
          type: object
          properties:
            description:
              type: string
            entities:
              type: object
              properties:
                description:
                  type: object
                  properties:
                    urls:
                      type: array
                      items:
                        type: object
                        properties:
                          display_url:
                            type: string
                          expanded_url:
                            type: string
                          indices:
                            type: array
                            items:
                              type: integer
                          url:
                            type: string
                url:
                  type: object
                  properties:
                    urls:
                      type: array
                      items:
                        type: object
                        properties:
                          display_url:
                            type: string
                          expanded_url:
                            type: string
                          indices:
                            type: array
                            items:
                              type: integer
                          url:
                            type: string
    UserFollowingsResponse:
      type: object
      properties:
        followings:
          type: array
          items:
            $ref: '#/components/schemas/User'
        has_next_page:
          type: boolean
        next_cursor:
          type: string
        status:
          type: string
          enum:
            - success
            - error
        message:
          type: string
    UserMentionsResponse:
      type: object
      properties:
        tweets:
          type: array
          items:
            $ref: '#/components/schemas/Tweet'
        has_next_page:
          type: boolean
        next_cursor:
          type: string
        status:
          type: string
          enum:
            - success
            - error
        message:
          type: string
    UserProfileAboutResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            userName:
              type: string
            createdAt:
              type: string
            isBlueVerified:
              type: boolean
            protected:
              type: boolean
            affiliates_highlighted_label:
              type: object
              properties:
                label:
                  type: object
                  properties:
                    badge:
                      type: object
                      properties:
                        url:
                          type: string
                    description:
                      type: string
                    url:
                      type: object
                      properties:
                        url:
                          type: string
                        urlType:
                          type: string
                    userLabelDisplayType:
                      type: string
                    userLabelType:
                      type: string
            about_profile:
              type: object
              properties:
                account_based_in:
                  type: string
                location_accurate:
                  type: boolean
                learn_more_url:
                  type: string
                affiliate_username:
                  type: string
                source:
                  type: string
                username_changes:
                  type: object
                  properties:
                    count:
                      type: string
            identity_profile_labels_highlighted_label:
              type: object
              properties:
                label:
                  type: object
                  properties:
                    description:
                      type: string
                    badge:
                      type: object
                      properties:
                        url:
                          type: string
                    url:
                      type: object
                      properties:
                        url:
                          type: string
                        urlType:
                          type: string
                    userLabelDisplayType:
                      type: string
                    userLabelType:
                      type: string
        status:
          type: string
          enum:
            - success
            - error
        msg:
          type: string
    UserTweetsResponse:
      type: object
      properties:
        tweets:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              id:
                type: string
              url:
                type: string
              text:
                type: string
              source:
                type: string
              retweetCount:
                type: integer
              replyCount:
                type: integer
              likeCount:
                type: integer
              quoteCount:
                type: integer
              viewCount:
                type: integer
              createdAt:
                type: string
              lang:
                type: string
              bookmarkCount:
                type: integer
              isReply:
                type: boolean
              inReplyToId:
                type: string
              conversationId:
                type: string
              displayTextRange:
                type: array
                items:
                  type: integer
              inReplyToUserId:
                type: string
              inReplyToUsername:
                type: string
        has_next_page:
          type: boolean
        next_cursor:
          type: string
        status:
          type: string
          enum:
            - success
            - error
        message:
          type: string
    VerifiedFollowersResponse:
      type: object
      properties:
        followers:
          type: array
          items:
            $ref: '#/components/schemas/User'
        status:
          type: string
          enum:
            - success
            - error
        message:
          type: string
    WebResult:
      type: object
      required:
        - title
        - link
        - snippet
      properties:
        title:
          type: string
          description: Title of the web page
        link:
          type: string
          format: uri
          description: URL to access the web page
        snippet:
          type: string
          description: Brief summary or preview of the web page content
        display_url:
          type: string
          description: Display-friendly URL
        published_date:
          type: string
          format: date-time
          description: Publication date of the web page
    WebSearchResponse:
      type: object
      required:
        - id
        - results
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        results:
          type: array
          items:
            $ref: '#/components/schemas/WebResult'
          description: List of web search results
