API reference overview

Every tool is a POST to /v1/tools/{name} at https://api.stockcontext.com, with a JSON body and your key in the X-API-Key header. There are no GET product endpoints and no query-string parameters — inputs go in the JSON body.

This generated reference is schema-aware. Schema 2 is the default when schema is omitted. Use { "schema": 1 } only for the frozen legacy wire.

curl -sS "https://api.stockcontext.com/v1/tools/stock_financials" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL", "periods": 1}'

Create keys on the dashboard keys page (https://stockcontext.com/dashboard/keys). See Authentication.

Endpoints

HTTP tool surface: 10 data tools + stock_flag, a feedback endpoint. stock_universe and stock_technicals are schema-2 only; the frozen schema-1 tools are unchanged. Each endpoint has a generated reference page with its full request schema and a response example.

Endpoint	Required	Optional	Purpose
`stock_search`	`query`	`limit` (1–50, default 10)	Resolve a ticker, name, or CIK to securities with coverage flags.
`stock_universe`	—	`coverage`, `shape`, `offset`, `limit` (1–500, default 100)	Enumerate active listings with database-derived coverage markers and published filer shapes.
`stock_financials`	`symbol`	`statement`, `period_kind`, `periods` (1–20, default 3), `vintage`, `detail`	Income statement, balance sheet, cash flow, and ratios with per-cell provenance.
`stock_overview`	`symbol`	`detail`	Profile, DEI, latest filings, financials, valuation, and growth in one call.
`stock_prices`	`symbol`	`view`, `range`, `interval`, `bars`, `indicators`, `detail`	Current/EOD bars, history, return/range context, dividends, and splits.
`stock_technicals`	`symbol`	`detail`, `indicators`, `range`, `bars`	Indicators, drawdowns, beta versus SPY, relative returns, and optional indicator history.
`stock_filings`	`symbol`	`form`, `limit` (1–100, default 20)	SEC filing inventory with accession, dates, and the primary document.
`stock_insider`	`symbol`	`window_days` (1–1827, default 90), `limit` (1–1000, default 200)	Form 4 insider transactions, faithfully transcribed.
`stock_ownership`	`symbol`	—	Tracked institutional 13F holders (a subset, never exhaustive).
`stock_reference`	`catalog`	`q`, `rule_id`	The API’s self-describing catalogs.
`stock_flag`	`symbol`, `field`	`period`, `reason`, `claimed_value`, `schema` (default 2)	Report a served value for human triage; it never edits served data.

Parameter values

stock_financials.statement — financials (default; all three statements), income, balance, or cash_flow.
stock_financials.period_kind — annual (default) or quarter.
stock_financials.vintage — latest_restated only. Historical variants are not documented for new integrations because schema 2 does not advertise or serve them.
detail (financials, overview) — concise (default) or full. full adds sources and hashes to each cell.
stock_prices.view — schema 2 defaults to snapshot; history and corporate_actions are depth views. technicals returns a 200 recovery redirect to stock_technicals.
stock_prices.range — 1M, 3M, 6M, 1Y (default), 5Y, or max.
stock_technicals.indicators — optional SMA/EMA/RSI/MACD/Bollinger/ATR history columns; range applies only when indicators are requested.
stock_reference.catalog — refusal_tokens, refusal_reasons, operating_rules, concepts, units, shapes, fields, capabilities, coverage, filing_forms, 8k_items, or form4_codes.
stock_flag — feedback endpoint only. It records a bounded report and returns { "data": { "received": true, "flag_id": "..." }, "meta": { "schema_version": "2" } } on success.

Response shape

A successful data tool returns a subject (the resolved entity and security), a data block, and a meta block:

{
  "subject": { "entity": { "cik": "...", "name": "..." }, "security": { "ticker": "AAPL" } },
  "data": { "...": "..." },
  "meta": { "schema_version": "2", "as_of": { "sec": "2026-06-26" } }
}

Individual values inside data are typed cells: exact compact cells like { "v": "112010000000", "d": "≈$112B" }, decimal strings in aligned statement arrays, JSON numbers for ratios, or refusal objects.

Refusal envelope

Any value — a single field or a whole tool result — that cannot be proven returns the same flat envelope, never an empty 200 and never a guessed number:

{
  "unavailable": "not_reported",
  "recovery": { "action": "use_full_document" }
}

Branch on unavailable. Look up any token or recovery.action in the refusal_tokens catalog. See Response model.

Authentication and limits

Send your key in X-API-Key. Requests without a valid key are rejected before any work is done.

Failure	HTTP	Meaning
`missing_api_key`	401	No `X-API-Key` header.
`invalid_api_key`	401	The key is unknown or revoked.
`rate_limit_exceeded`	429	Per-minute rate limit for your plan.
`quota_exhausted`	429	Daily (Free) or monthly (Starter/Builder) quota used up.
`no_match`	404	No exact subject match, or the requested data cannot be found for schema 2.
`request_too_large`	413	Body exceeded the 64 KiB cap or nesting guard.
Validation error	422	The request body failed schema validation; `detail` names the field.

Plan limits:

Plan	Quota	Rate	Price
Free	100 / day	30 / min	$0
Starter	10,000 / month	60 / min	$29 / mo
Builder	75,000 / month	300 / min	$99 / mo

Authenticated tool responses include X-Credits-Remaining when Unkey reports remaining credits, and include X-RateLimit-Remaining / X-RateLimit-Reset when Unkey reports rate-limit state. See Plans and limits for the exact header behavior, including schema-2 304 responses.

Reference catalogs

The API describes itself. stock_reference serves deterministic catalogs so an agent can resolve tokens at runtime instead of hard-coding them:

Catalog	Contents
`refusal_tokens`	Every refusal `reason` and its `recovery_action`.
`operating_rules`	The derivation rules (`rule_id`) behind derived values.
`concepts`	The XBRL concepts mapped to each served field.
`units`	Unit policies: ISO-4217 money, ISO-4217 per share, shares, and ratios.
`shapes`	The filer shapes (operating, bank, REIT, insurer, IFRS, BDC, broker-dealer).
`filing_forms`	The SEC form types the API recognizes.
`8k_items`	The 8-K item codes and their meanings.

Generated pages

The endpoint pages under this section are generated from the schema-aware structural OpenAPI document. It models request parameters, the schema selector, HTTP statuses, and envelope-level response shapes. Captured examples remain authoritative for full nested payload detail. The frozen legacy wire remains reachable as the Schema 1 appendix.

API reference

Schema 2

Schema 1 frozen legacy

Discovery

Financials

Market data

Filings & activity

Endpoints

Parameter values

Response shape

Refusal envelope

Authentication and limits

Reference catalogs

Generated pages

​Endpoints

​Parameter values

​Response shape

​Refusal envelope

​Authentication and limits

​Reference catalogs

​Generated pages

Endpoints

Parameter values

Response shape

Refusal envelope

Authentication and limits

Reference catalogs

Generated pages