> ## 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. # Company overview > Profile, shares, SEC-verified valuation, growth, and latest filings in one call. Schema 2 field names below match the `stock_reference` fields catalog. If a value cannot be proven, the response carries a typed refusal object instead of `0`, `null`, or an inferred value. ## 2026-07-07 field wave | Field | Block | Description and basis | Refusal / guard behavior | | ------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `revenue_per_share` | `valuation` | Latest revenue divided by `weighted_avg_shares_basic`; serves with `basis: "weighted_avg_shares_basic"`. | Refuses when revenue or weighted shares are unavailable, or when the share denominator is non-positive. | | `tangible_book_value_per_share` | `valuation` | Book equity minus goodwill and intangible assets, divided by shares; basis is `tangible_parent_equity_per_share` or `tangible_total_equity_per_share`. | Refuses with `valuation_operand_unavailable` for missing goodwill, intangible assets, equity, or shares; non-positive share denominators refuse. | | `dividends_per_share` | `valuation` | Direct annual common DPS from facts; serves as `{"value": n, "basis": "declared"}` or `{"value": n, "basis": "cash_paid"}`. | Refuses when the DPS fact is absent or ambiguous; class-dimensioned DPS rows that differ do not serve. | | `earnings_yield_pct` | `valuation` | Net income divided by market cap, percent-points; serves with a vintage-prefixed basis (`basis: "FY2025_annual_net_income_over_market_cap"`, or `basis: "ttm"` + `ttm_periods` when the TTM magnitude derives). | Serves signed for loss years. A loss-year `price_to_earnings` refusal points here with `use_alternative_field`. | | `ebitda_margin_pct` | `analysis.margins_pct` | EBITDA margin; EBITDA is `operating_income + depreciation_amortization`. | Refuses when EBITDA operands are unavailable or revenue is non-positive. | | `roce_pct` | `analysis.returns_pct` | Operating income over average two-FY capital employed; serves with `basis: "avg_2fy_capital_employed"`. | Refuses when required current/prior balance operands are unavailable or capital employed is non-positive. | | `debt_to_assets` | `analysis.leverage` | Total debt divided by total assets. | Refuses when debt or assets are unavailable, or when assets are non-positive. | | `cash_ratio` | `analysis.leverage` | Cash, plus short-term investments when served, divided by current liabilities; basis is `cash_only` or `cash_and_short_term_investments`. | Refuses when cash or current liabilities are unavailable, or when current liabilities are non-positive. | | `ocf_ratio` | `analysis.leverage` | Operating cash flow divided by current liabilities. | Refuses when either operand is unavailable, or when current liabilities are non-positive. | | `effective_tax_rate` | `analysis.quality` | Derived income tax expense divided by pretax income; a ratio, not percent-points. | Refuses when the derived tax-rate cell is unavailable, ambiguous, or mathematically undefined. | | `asset_turnover` | `analysis.quality` | Revenue divided by average two-FY total assets; serves with `basis: "avg_2fy_total_assets"`. | Refuses when revenue or either asset operand is unavailable, or when average assets are non-positive. | | `inventory_turnover` | `analysis.efficiency` | Cost of revenue divided by average two-FY inventory; serves with `basis: "avg_2fy_inventory"`. | Refuses when cost of revenue, latest inventory, or prior inventory is unavailable; non-positive average inventory refuses. | | `receivables_turnover` | `analysis.efficiency` | Revenue divided by average two-FY accounts receivable; serves with `basis: "avg_2fy_accounts_receivable"`. | Refuses when revenue, latest receivables, or prior receivables is unavailable; non-positive average receivables refuse. | | `payables_turnover` | `analysis.efficiency` | Cost of revenue divided by average two-FY accounts payable; serves with `basis: "avg_2fy_accounts_payable"`. | Refuses when cost of revenue, latest payables, or prior payables is unavailable; non-positive average payables refuse. | | `days_sales_outstanding` | `analysis.efficiency` | `365 / receivables_turnover`, rounded to one decimal day. | Reuses the `receivables_turnover` refusal when the parent metric does not serve. | | `days_inventory_outstanding` | `analysis.efficiency` | `365 / inventory_turnover`, rounded to one decimal day. | Reuses the `inventory_turnover` refusal when the parent metric does not serve. | | `days_payables_outstanding` | `analysis.efficiency` | `365 / payables_turnover`, rounded to one decimal day. | Reuses the `payables_turnover` refusal when the parent metric does not serve. | | `cash_conversion_cycle` | `analysis.efficiency` | `days_sales_outstanding + days_inventory_outstanding - days_payables_outstanding`, using the same 365-day convention. | Reuses the first refused day metric; no point-in-time fallback is used. | Shape-specific impossibilities are declared once in `not_applicable_for_shape`. Financial institutions and REITs exclude the operating-company efficiency fields when the statement face does not support them. ## OpenAPI ````yaml POST /v1/tools/stock_overview openapi: 3.1.0 info: title: StockContext API version: '2026-07-10' summary: Schema-aware structural reference for StockContext tools. description: >- This OpenAPI document is structural and schema-aware: request schemas, the schema selector, HTTP statuses, and envelope-level response forms are modeled from the live API boundary. Captured examples remain authoritative for full nested payload detail. servers: - url: https://api.stockcontext.com description: Production API security: [] tags: - name: Discovery description: Search, catalogs, and value-flag feedback. - name: Financials description: SEC-verified fundamentals and overviews. - name: Market data description: Licensed price feed. - name: Filings and activity description: SEC filings, insiders, and tracked holders. paths: /v1/tools/stock_overview: post: tags: - Financials summary: Get a company overview description: >- Company profile, latest filings, financials, valuation, growth, and provenance in one call. operationId: stock_overview requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OverviewRequest' examples: request: summary: Request value: symbol: AAPL schema: 2 detail: core responses: '200': description: >- Get a company overview. Envelope-level schema; captured examples remain authoritative for full nested payload detail. content: application/json: schema: $ref: '#/components/schemas/Schema2Envelope' examples: success: summary: Schema 2 response value: subject: entity: cik: '0000320193' name: Apple Inc. reporting_currency: USD security: ticker: AAPL trading_currency: USD data: answer: title: Apple Inc. summary: >- Schema-2 overview payload; see captured examples for full fields. meta: schema_version: '2' as_of: sec: '2026-06-26' '304': $ref: '#/components/responses/NotModified' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/RequestTooLarge' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalFailure' security: - ApiKeyAuth: [] x-codeSamples: - lang: bash label: curl source: |- curl -sS "https://api.stockcontext.com/v1/tools/stock_overview" \ -H "X-API-Key: $STOCKCONTEXT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"symbol":"AAPL","schema":2,"detail":"core"}' components: schemas: OverviewRequest: type: object description: Request body for stock_overview. additionalProperties: false required: - symbol properties: symbol: type: string description: Ticker or resolvable symbol. minLength: 1 maxLength: 24 detail: type: string enum: - concise - full - core - audit description: >- Schema 1 accepts concise/full. Schema 2 maps omitted or concise to core and accepts core/full/audit. default: concise schema: type: integer enum: - 1 - 2 default: 2 description: >- Response schema selector. Omit (or send 2) for the schema-2 envelope, the default; 1 selects the frozen legacy wire. Boolean values are rejected by the API boundary. Schema2Envelope: type: object description: >- Schema-2 envelope. The OpenAPI schema is structural; captured examples are authoritative for full nested payload detail. additionalProperties: false required: - data - meta properties: subject: $ref: '#/components/schemas/Subject' data: type: object description: Tool payload or typed schema-2 refusal. additionalProperties: true meta: $ref: '#/components/schemas/MetaV2' Subject: type: object description: Resolved entity and security when the tool has a single subject. additionalProperties: false properties: entity: type: object description: Entity identity and reporting metadata. additionalProperties: true security: type: object description: Security identity and trading metadata. additionalProperties: true MetaV2: type: object description: >- Schema-2 metadata. Unknown optional fields are omitted, not emitted as null. additionalProperties: false required: - schema_version properties: schema_version: type: string enum: - '2' policy_version: type: string as_of: type: object additionalProperties: false properties: sec: type: string description: SEC ingestion cursor date. market: type: string description: Market-data cursor date. published_at: type: string format: date-time basis: type: string units: type: object additionalProperties: type: string parser: type: object additionalProperties: false properties: name: type: string version: type: string build: type: object additionalProperties: type: string last_verified_at: type: string format: date-time truncated: type: boolean deprecation: type: object description: Alias or sunset notices for schema-2 responses. additionalProperties: true FlatRefusal: type: object description: >- Flat refusal body used by auth, body-limit, schema-1 tool refusals, and some HTTP failures. additionalProperties: false required: - available - reason properties: available: type: boolean enum: - false reason: type: string recovery: type: object description: Recovery instruction. Omitted when no recovery exists. additionalProperties: true FastAPIValidationError: type: object description: Schema-1/no-schema request validation shape from FastAPI. additionalProperties: true required: - detail properties: detail: type: array items: type: object description: Validation issue. additionalProperties: true Schema2ValidationErrorEnvelope: type: object additionalProperties: false required: - data - meta properties: data: allOf: - $ref: '#/components/schemas/Schema2RefusalData' properties: unavailable: type: string enum: - invalid_request meta: $ref: '#/components/schemas/MetaV2' Schema2RefusalData: type: object description: Schema-2 typed refusal payload. additionalProperties: true required: - unavailable properties: unavailable: type: string recovery: type: object description: Executable recovery instruction when one exists. additionalProperties: true errors: type: array items: type: object description: Validation issue. additionalProperties: true missing_operand: type: string affects: type: array items: type: string note: type: string responses: NotModified: description: >- Schema-2 conditional request matched If-None-Match. The response has no body. Unauthorized: description: Missing, invalid, revoked, or unpaid API key. Flat refusal body. content: application/json: schema: $ref: '#/components/schemas/FlatRefusal' examples: missing_api_key: summary: Missing API key value: available: false reason: missing_api_key NotFound: description: >- No exact subject match or no matching data. Schema 2 uses an envelope; schema 1/tool-level failures can use the flat refusal body. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Schema2Envelope' - $ref: '#/components/schemas/FlatRefusal' examples: no_match: summary: Schema 2 no_match value: data: unavailable: no_match recovery: action: use_tool tool: stock_search params: query: ZZZZ meta: schema_version: '2' RequestTooLarge: description: >- Request body exceeded the 64 KiB cap or nesting guard. Flat refusal body. content: application/json: schema: $ref: '#/components/schemas/FlatRefusal' examples: request_too_large: summary: Request too large value: available: false reason: request_too_large ValidationError: description: >- Request validation failure. Schema 1/no-schema requests keep FastAPI detail; schema 2 uses invalid_request inside the schema-2 envelope. content: application/json: schema: oneOf: - $ref: '#/components/schemas/FastAPIValidationError' - $ref: '#/components/schemas/Schema2ValidationErrorEnvelope' examples: schema_1: summary: Schema 1 validation value: detail: - loc: - body - symbol msg: Field required type: missing schema_2: summary: Schema 2 invalid_request value: data: unavailable: invalid_request recovery: action: fix_request errors: - param: schema given: true expected: integer 1 or 2 meta: schema_version: '2' TooManyRequests: description: >- Per-minute rate limit or plan quota refusal. Retry-After is present only for the per-minute window. content: application/json: schema: oneOf: - $ref: '#/components/schemas/FlatRefusal' - $ref: '#/components/schemas/Schema2Envelope' examples: rate_limit_exceeded: summary: Rate limit value: available: false reason: rate_limit_exceeded recovery: action: wait seconds: 60 InternalFailure: description: >- Internal service failure. Flat refusal body when surfaced by the API refusal layer. content: application/json: schema: $ref: '#/components/schemas/FlatRefusal' examples: internal_error: summary: Internal failure value: available: false reason: internal_error securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````