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

# API reference overview

> Base URL, the X-API-Key header, the tool endpoints and their parameters, rate limits and quotas, and the refusal envelope.

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.

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

```bash theme={null}
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](/docs/reference/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`](/docs/api-reference/endpoints/discovery/stock_search)                  | `query`           | `limit` (1–50, default 10)                                                   | Resolve a ticker, name, or CIK to securities with coverage flags.                            |
| [`stock_universe`](/docs/api-reference/endpoints/discovery/stock_universe)              | —                 | `coverage`, `shape`, `offset`, `limit` (1–500, default 100)                  | Enumerate active listings with database-derived coverage markers and published filer shapes. |
| [`stock_financials`](/docs/api-reference/endpoints/financials/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`](/docs/api-reference/endpoints/financials/stock_overview)             | `symbol`          | `detail`                                                                     | Profile, DEI, latest filings, financials, valuation, and growth in one call.                 |
| [`stock_prices`](/docs/api-reference/endpoints/market-data/stock_prices)                | `symbol`          | `view`, `range`, `interval`, `bars`, `indicators`, `detail`                  | Current/EOD bars, history, return/range context, dividends, and splits.                      |
| [`stock_technicals`](/docs/api-reference/endpoints/market-data/stock_technicals)        | `symbol`          | `detail`, `indicators`, `range`, `bars`                                      | Indicators, drawdowns, beta versus SPY, relative returns, and optional indicator history.    |
| [`stock_filings`](/docs/api-reference/endpoints/filings-and-activity/stock_filings)     | `symbol`          | `form`, `limit` (1–100, default 20)                                          | SEC filing inventory with accession, dates, and the primary document.                        |
| [`stock_insider`](/docs/api-reference/endpoints/filings-and-activity/stock_insider)     | `symbol`          | `window_days` (1–1827, default 90), `limit` (1–1000, default 200)            | Form 4 insider transactions, faithfully transcribed.                                         |
| [`stock_ownership`](/docs/api-reference/endpoints/filings-and-activity/stock_ownership) | `symbol`          | —                                                                            | Tracked institutional 13F holders (a subset, never exhaustive).                              |
| [`stock_reference`](/docs/api-reference/endpoints/discovery/stock_reference)            | `catalog`         | `q`, `rule_id`                                                               | The API's self-describing catalogs.                                                          |
| [`stock_flag`](/docs/api-reference/endpoints/discovery/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:

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

```json theme={null}
{
  "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](/docs/reference/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](/docs/reference/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](/docs/api-reference/schema-1-appendix).