Skip to main content
stock_reference is the schema-2 self-documentation entrypoint. Call it once per agent session and cache the result. Schema 2 is not the default yet. Send "schema": 2 explicitly.

​
Capabilities

curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"catalog":"capabilities"}'
Trimmed from tests/fixtures/v2_golden/reference_capabilities.json; shown values are unchanged. 
{
  "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": "every tool accepts schema 1|2 (default 1); 2 selects this envelope"
    },
    "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": 1406, "gate": 2200 },
        "stock_financials_income": { "measured": 514, "gate": 1000 },
        "stock_financials_quarterly_income": { "measured": 646, "gate": 1100 },
        "stock_prices_snapshot": { "measured": 357, "gate": 500 },
        "stock_insider": { "measured": 1319, "gate": 2200 },
        "stock_ownership": { "measured": 1621, "gate": 2600 }
      }
    }
  },
  "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 '{"schema":2,"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 '{"schema":2,"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 complete set of servable fields and possible refusal reasons: 
curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"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. 
{
  "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 '{"schema":2,"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. It is not part of the current schema-1 OpenAPI appendix. 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": {}
    }
  }
}
When you use it in a schema-2 environment, keep the schema explicit: 
{ "schema": 2, "symbol": "AAPL", "field": "revenue", "period": "FY2025" }
Do not assume stock_flag is available from the schema-1 generated endpoint list; ask stock_reference for capabilities first.