> ## Documentation Index
> Fetch the complete documentation index at: https://noxstock.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema 2 reference catalogs

> Capabilities, coverage, fields, shapes, refusal reasons, and stock_flag as the schema-2 self-documentation layer.

`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

```bash theme={null}
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.

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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.

```json theme={null}
{
  "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:

```bash theme={null}
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.

```json theme={null}
{
  "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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```json theme={null}
{ "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.