# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Massive Com Reference API
  version: 1.0.0
extends: openapi/massive-com-reference-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/stocks/filings/10-K/vX/sections'].get
  update:
    x-apievangelist-phrasing:
      intent: Read sections of 10-K filings (vX)
      effect: read
      questions:
      - Can I pull the raw text of a specific section, like risk factors or MD&A, from a company's 10-K?
      - Where can I read the business description section of an annual report?
      instructions:
      - text: Get 10-K section text for {ticker} using the vX sections endpoint.
        slots:
          ticker: query.ticker
      - text: Pull the {section} section from {ticker}'s 10-K filings via vX.
        slots:
          section: query.section
          ticker: query.ticker
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/filings/10-K/vX_0/sections'].get
  update:
    x-apievangelist-phrasing:
      intent: Read sections of 10-K filings (vX_0 variant)
      effect: read
      questions:
      - Is there a vX_0 version of the 10-K sections endpoint I can call instead?
      - Can I fetch annual report section text by CIK from the vX_0 path?
      instructions:
      - text: Get 10-K section text for CIK {cik} from the vX_0 endpoint.
        slots:
          cik: query.cik
      - text: Pull the {section} section filed on {filing_date} using vX_0.
        slots:
          section: query.section
          filing_date: query.filing_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/filings/8-K/vX/disclosures'].get
  update:
    x-apievangelist-phrasing:
      intent: Get categorized 8-K disclosures
      effect: read
      questions:
      - What kind of material event did a company disclose in its latest 8-K?
      - Can I find 8-K filings tagged with a specific disclosure category?
      instructions:
      - text: List categorized 8-K disclosures for {tickers}.
        slots:
          tickers: query.tickers
      - text: Find 8-K disclosures in tertiary category {tertiary_category}.
        slots:
          tertiary_category: query.tertiary_category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/filings/8-K/vX/text'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the text of 8-K current reports
      effect: read
      questions:
      - Can I read the full parsed text of a company's 8-K about an acquisition or executive change?
      - What did a company announce in the 8-K it filed on a given date?
      instructions:
      - text: Get parsed 8-K filing text for {ticker}.
        slots:
          ticker: query.ticker
      - text: Show 8-K text filed by {ticker} on {filing_date}.
        slots:
          ticker: query.ticker
          filing_date: query.filing_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/filings/vX/13-F'].get
  update:
    x-apievangelist-phrasing:
      intent: Get institutional 13F holdings filings
      effect: read
      questions:
      - What stocks does a large institutional investment manager hold?
      - Which 13F reports were filed in the last quarter?
      instructions:
      - text: Get 13F holdings filed by manager CIK {filer_cik}.
        slots:
          filer_cik: query.filer_cik
      - text: List 13F filings submitted on {filing_date}.
        slots:
          filing_date: query.filing_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/filings/vX/form-3'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Form 3 initial insider ownership filings
      effect: read
      questions:
      - Who became a new insider at a company and filed an initial ownership statement?
      - Can I see Form 3 filings by a newly appointed director?
      instructions:
      - text: List Form 3 initial ownership filings for {tickers}.
        slots:
          tickers: query.tickers
      - text: Show Form 3 filings by insider CIK {owner_cik}.
        slots:
          owner_cik: query.owner_cik
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/filings/vX/form-4'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Form 4 insider transaction filings
      effect: read
      questions:
      - Have any executives bought or sold shares of a stock recently?
      - Can I filter insider trades by transaction code, like open-market purchases?
      instructions:
      - text: List Form 4 insider transactions for {tickers}.
        slots:
          tickers: query.tickers
      - text: Show Form 4 filings with transaction code {transaction_code}.
        slots:
          transaction_code: query.transaction_code
      - text: Get insider trades filed by owner CIK {owner_cik} since {filing_date_gte}.
        slots:
          owner_cik: query.owner_cik
          filing_date_gte: query.filing_date.gte
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/filings/vX/index'].get
  update:
    x-apievangelist-phrasing:
      intent: Search the SEC EDGAR filings index
      effect: read
      questions:
      - Where can I find links to every SEC filing a company has made?
      - Which forms did a company file with the SEC on a certain date?
      instructions:
      - text: List EDGAR index entries for {ticker}.
        slots:
          ticker: query.ticker
      - text: Find {form_type} filings in the EDGAR index filed on {filing_date}.
        slots:
          form_type: query.form_type
          filing_date: query.filing_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/filings/vX/risk-factors'].get
  update:
    x-apievangelist-phrasing:
      intent: Get risk factors from a company's 10-K
      effect: read
      questions:
      - What risk factors did a company identify in its annual report?
      - Have a company's disclosed risks changed since last year's 10-K?
      instructions:
      - text: Get the 10-K risk factors for {ticker}.
        slots:
          ticker: query.ticker
      - text: Show risk factors disclosed by CIK {cik} since {filing_date_gte}.
        slots:
          cik: query.cik
          filing_date_gte: query.filing_date.gte
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/taxonomies/vX/disclosures'].get
  update:
    x-apievangelist-phrasing:
      intent: List the 8-K disclosure classification taxonomy
      effect: read
      questions:
      - What categories are used to classify 8-K disclosures?
      - Which secondary categories sit under a primary 8-K disclosure category?
      instructions:
      - text: List the 8-K disclosure taxonomy.
      - text: Show 8-K disclosure classifications under primary category {primary_category}.
        slots:
          primary_category: query.primary_category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/taxonomies/vX/risk-factors'].get
  update:
    x-apievangelist-phrasing:
      intent: List the risk factor classification taxonomy
      effect: read
      questions:
      - What categories are used to classify 10-K risk factors?
      - Which tertiary risk classifications fall under a secondary risk category?
      instructions:
      - text: List the risk factor taxonomy.
      - text: Show risk factor classifications under secondary category {secondary_category}.
        slots:
          secondary_category: query.secondary_category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/v1/short-interest'].get
  update:
    x-apievangelist-phrasing:
      intent: Get FINRA short interest for a stock
      effect: read
      questions:
      - How many shares of a stock are sold short as of the last settlement date?
      - Which stocks have a days-to-cover ratio above 10?
      instructions:
      - text: Get short interest for {ticker}.
        slots:
          ticker: query.ticker
      - text: Find stocks with days to cover above {days_to_cover_gt}.
        slots:
          days_to_cover_gt: query.days_to_cover.gt
      - text: Show short interest reported for settlement date {settlement_date}.
        slots:
          settlement_date: query.settlement_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/v1/short-volume'].get
  update:
    x-apievangelist-phrasing:
      intent: Get daily short sale volume
      effect: read
      questions:
      - What share of today's trading volume in a stock was short selling?
      - Which tickers had a short volume ratio above half on a given day?
      instructions:
      - text: Get daily short volume for {ticker}.
        slots:
          ticker: query.ticker
      - text: Show short volume for {ticker} on {date}.
        slots:
          ticker: query.ticker
          date: query.date
      - text: Find tickers with a short volume ratio above {short_volume_ratio_gt}.
        slots:
          short_volume_ratio_gt: query.short_volume_ratio.gt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stocks/vX/float'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a stock's free float
      effect: read
      questions:
      - How many shares of a company are actually available for public trading?
      - Which stocks have a free float below 20 percent?
      instructions:
      - text: Get the free float for {ticker}.
        slots:
          ticker: query.ticker
      - text: List stocks with free float percent under {free_float_percent_lt}.
        slots:
          free_float_percent_lt: query.free_float_percent.lt
      method: generated
      generated: '2026-09-26'