> ## 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.

# Versioning

> Schema 1 is the current default wire. Schema 2 is opt-in during Waves 1-2 and will become the default after the migration window.

StockContext currently serves **schema 1 by default**. If you omit `schema`, you get schema 1.

Schema 2 is the next wire format. During Waves 1-2 it is opt-in per request:

```json theme={null}
{ "schema": 2, "symbol": "AAPL" }
```

Every schema-2 example in these docs includes `"schema": 2` in the request body on purpose. Do not rely on defaults when testing the new shape.

## Why schema 2 exists

Schema 2 keeps the same product rule — refuse, never fabricate — but changes the wire shape so agents can read more signal with fewer repeated bytes:

* one envelope on every response: `subject`, `data`, `meta`
* typed refusals with `unavailable` as the discriminator
* columnar financial statements with aligned `periods` and `fields`
* hoisted provenance: source facts once per block, audit detail on demand
* explicit staleness: SEC and market clocks stay separate
* measured token budgets published by the capabilities catalog

## Migration plan

During **Wave 1**, tools add schema 2 one slice at a time. If a tool has not migrated yet, a schema-2 request returns a normal envelope with a typed refusal:

```json theme={null}
{
  "data": {
    "unavailable": "schema_not_yet_available_for_tool",
    "recovery": { "action": "supply_params", "params": { "schema": 1 } }
  },
  "meta": { "schema_version": "2" }
}
```

During **Wave 2**, schema 2 becomes the default after 60 days or after more than 80% of traffic sends `"schema": 2`. Schema 1 remains available with `"schema": 1` for 90 more days and responses carry `meta.deprecation`.

During **Wave 3**, schema 1 is removed after schema-2 `detail: "audit"` is verified byte-complete against the old evidence trail.

## Which docs to use

* Use the generated [API reference](/api-reference/overview) for the current default schema.
* Use the [Schema 2 pages](/schema-2/overview) when you are explicitly sending `"schema": 2`.
* Keep schema selection in your request body until the default flip is announced.

## OpenAPI status

The generated endpoint pages are still built from the current default schema-1 OpenAPI snapshot. `openapi.v1.json` is the explicit versioned copy; `openapi.json` remains the Mintlify compatibility alias. Schema-2 examples in this section are fixture-backed MDX examples until the schema-2 OpenAPI snapshot ships as its own versioned contract.