Schema 2 reference catalogs

stock_reference is the schema-2 self-documentation entrypoint. Call it once per agent session and cache the result. Schema 2 is the default. You can omit schema in new requests.

Capabilities

curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog":"capabilities"}'

Trimmed from tests/fixtures/v2_golden/reference_capabilities.json.

{
  "data": {
    "catalog": "capabilities",
    "conventions": {
      "refusals": "a refusal is any object carrying the key 'unavailable'",
      "percent": "*_pct and *_pp values are percent-points, never fractions",
      "typing": "filed and derived-exact values are decimal strings; computed values are JSON numbers",
      "display_twins": "d strings are display-only approximations; always parse v",
      "series_decode": "x => typeof x === \"object\" ? null : Number(x) maps refusal cells to chart gaps",
      "schema": "omitted schema selects schema 2; schema 1 is frozen legacy via explicit {\"schema\":1}",
      "quarterly": "quarter/ytd serve where 10-Q build landed; else quarterly_not_yet_supported or interim_not_filed_with_sec; schema:2 quarter omitting periods defaults to 5"
    },
    "token_budgets": {
      "measure": "minified_utf8_bytes_over_3_8",
      "note": "measured = CI golden minified wire bytes / 3.8; gate = SHAPES2 section 3.0",
      "calls": {
        "stock_overview_core": { "measured": 1739, "gate": 2200 },
        "stock_financials_income": { "measured": 579, "gate": 1000 },
        "stock_financials_quarterly_income": { "measured": 810, "gate": 1100 },
        "stock_prices_snapshot": { "measured": 292, "gate": 350 },
        "stock_technicals_core": { "measured": 305, "gate": 400 },
        "stock_insider": { "measured": 1319, "gate": 2200 },
        "stock_ownership": { "measured": 1319, "gate": 2600 },
        "stock_universe": { "measured": 2481, "gate": 3000 }
      }
    }
  },
  "meta": { "schema_version": "2" }
}

These budget numbers are measured. They are not marketing estimates.

Coverage as data

The capabilities fixture lists coverage as a stock_reference.catalog value:

curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog":"coverage"}'

Use this catalog as the live source for coverage counts. These docs do not quote a company-count claim because this repo does not include a committed reference_coverage fixture. For per-security coverage, stock_search still gives the preflight:

curl -sS "https://api.stockcontext.com/v1/tools/stock_search" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"JP MORGAN"}'

Trimmed from tests/fixtures/v2_golden/search_jpmorgan.json; shown values are unchanged.

{
  "data": {
    "query": "JP MORGAN",
    "match_basis": "exact",
    "matches": [
      {
        "security_id": "sec_0000019617_jpm",
        "ticker": "JPM",
        "exchange": "XNYS",
        "exchange_name": "NYSE",
        "match_type": "name_contains",
        "entity": { "cik": "0000019617", "name": "JPMORGAN CHASE & CO", "shape": "bank" },
        "coverage": { "financials": true, "prices": true }
      }
    ]
  },
  "meta": { "schema_version": "2" }
}

Fields and shapes

Use the fields catalog for the generated servable field set and possible refusal reasons. It is built from financials_cells.FACE_ORDER, overview_valuation.valuation_members, and overview_analysis.analysis_fields; do not treat the prose table below as the contract.

curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog":"fields"}'

Trimmed from tests/fixtures/v2_golden/reference_fields.json. Shape-specific financial fields include fee_income for ifrs_bank and insurance_revenue for ifrs_insurer; generic revenue remains requestable for those sub-shapes but refuses with not_applicable_for_shape instead of aliasing to the specialty field. The 2026-07-08 field-reference sync checked these catalog names against the render wiring:

Field	Endpoint	Catalog notes
`revenue_per_share`	`stock_overview`	Valuation member; basis `weighted_avg_shares_basic`.
`tangible_book_value_per_share`	`stock_overview`	Valuation member; basis names tangible parent or total equity per share.
`dividends_per_share`	`stock_overview`, `stock_financials`	Direct common DPS; basis `declared` or `cash_paid` when served in overview.
`earnings_yield_pct`	`stock_overview`	Signed net-income yield; P/E loss-year refusals point here.
`cash_ratio`	`stock_overview`	Analysis leverage ratio; basis `cash_only` or `cash_and_short_term_investments`.
`ocf_ratio`	`stock_overview`	Analysis leverage ratio over current liabilities.
`ebitda_margin_pct`	`stock_overview`	Analysis margin; EBITDA is operating income plus D&A.
`effective_tax_rate`	`stock_overview`, `stock_financials`	Derived tax-rate ratio; not percent-points.
`asset_turnover`	`stock_overview`	Analysis quality ratio; basis `avg_2fy_total_assets`.
`roce_pct`	`stock_overview`	Analysis return; basis `avg_2fy_capital_employed`.
`debt_to_assets`	`stock_overview`	Analysis leverage ratio.
`inventory_turnover`	`stock_overview`	Efficiency sub-block; basis `avg_2fy_inventory`.
`receivables_turnover`	`stock_overview`	Efficiency sub-block; basis `avg_2fy_accounts_receivable`.
`payables_turnover`	`stock_overview`	Efficiency sub-block; basis `avg_2fy_accounts_payable`.
`days_sales_outstanding`	`stock_overview`	Efficiency days metric using `365 / receivables_turnover`.
`days_inventory_outstanding`	`stock_overview`	Efficiency days metric using `365 / inventory_turnover`.
`days_payables_outstanding`	`stock_overview`	Efficiency days metric using `365 / payables_turnover`.
`cash_conversion_cycle`	`stock_overview`	Efficiency days metric: DSO + DIO - DPO.
`interest_expense`	`stock_financials`	Operating income-statement field; ambiguous captive-finance candidates refuse.
`price_to_earnings`	`stock_overview`	Valuation member over EPS; loss-year cases refuse and point to `earnings_yield_pct`.
`price_to_book`	`stock_overview`	Valuation member over total or parent equity.
`price_to_sales`	`stock_overview`	Valuation member over revenue.
`price_to_fcf`	`stock_overview`	Valuation member over free cash flow.
`enterprise_value`	`stock_overview`	Valuation member: market cap + total debt - cash.
`ev_to_ebitda`	`stock_overview`	Valuation member over computed EBITDA.
`ev_to_sales`	`stock_overview`	Valuation member over revenue.
`ebitda`	`stock_overview`	Valuation member computed from operating income plus D&A.
`fcf_yield_pct`	`stock_overview`	Valuation yield over free cash flow and market cap.
`dividend_yield_pct`	`stock_overview`	Cash-return valuation member over dividends paid and market cap.
`buyback_yield_pct`	`stock_overview`	Cash-return valuation member over gross repurchases and market cap.
`payout_ratio`	`stock_overview`	Cash-return valuation member over dividends paid and net income.
`book_value_per_share`	`stock_overview`	Valuation member over total or parent equity per share.
`fcf_per_share`	`stock_overview`	Valuation member over free cash flow per share.
`dividends_to_ocf`	`stock_overview`	REIT valuation member inserted after `payout_ratio`.

{
  "data": {
    "catalog": "fields",
    "items": [
      {
        "field": "revenue",
        "endpoint": "stock_financials",
        "statement": "income_statement",
        "unit_policy": "iso4217",
        "shapes": ["operating_company", "reit", "ifrs", "ifrs_bank", "ifrs_insurer", "investment_company", "broker_dealer"],
        "possible_refusals": ["not_reported", "verification_pending", "oracle_contradicted", "not_applicable_for_shape"]
      },
      {
        "field": "fee_income",
        "endpoint": "stock_financials",
        "statement": "income_statement",
        "unit_policy": "iso4217",
        "shapes": ["ifrs_bank"],
        "possible_refusals": ["not_reported", "verification_pending", "oracle_contradicted"]
      },
      {
        "field": "insurance_revenue",
        "endpoint": "stock_financials",
        "statement": "income_statement",
        "unit_policy": "iso4217",
        "shapes": ["ifrs_insurer"],
        "possible_refusals": ["not_reported", "verification_pending", "oracle_contradicted"]
      }
    ]
  },
  "meta": { "schema_version": "2" }
}

Use the shapes catalog for routing status. IFRS bank and insurer handling appears as data.applies_to sub-shape tokens (ifrs_bank, ifrs_insurer), not as separate router shapes.

curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog":"shapes"}'

Trimmed from tests/fixtures/v2_golden/reference_shapes.json; shown values are unchanged.

{
  "data": {
    "catalog": "shapes",
    "items": [
      { "shape": "operating_company", "financials_status": "implemented", "route_basis": "default" },
      { "shape": "bank", "financials_status": "implemented", "route_basis": "SIC 6020-6199, 6712" },
      { "shape": "shell_blank_check", "financials_status": "not_served", "route_basis": "DEI shell flag plus corroborating face facts" }
    ]
  },
  "meta": { "schema_version": "2" }
}

`stock_flag`

stock_flag appears in the schema-2 capabilities catalog as a feedback endpoint. It is not a data tool and is not exposed over MCP. Trimmed from tests/fixtures/v2_golden/reference_capabilities.json; shown values are unchanged.

{
  "stock_flag": {
    "params": {
      "symbol": { "required": true },
      "field": { "required": true },
      "period": {},
      "reason": {},
      "claimed_value": {}
    }
  }
}

New requests can omit schema:

{ "symbol": "AAPL", "field": "revenue", "period": "FY2025" }

Use it only to report a suspected bad served value for human triage. It never edits served data.

API reference

Schema 2

Schema 1 frozen legacy

Discovery

Financials

Market data

Filings & activity

Schema 2 reference catalogs

Capabilities

Coverage as data

Fields and shapes

`stock_flag`

​Capabilities

​Coverage as data

​Fields and shapes

​stock_flag

Capabilities

Coverage as data

Fields and shapes

`stock_flag`