Skip to main content
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: 
{ "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: 
{
  "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 for the current default schema.
  • Use the Schema 2 pages 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.