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

# Financial statements

> SEC-verified income statement, balance sheet, cash flow, and ratios with per-cell provenance.

Schema 2 `stock_financials` is the statement-face source for the fields below. Served cells are filed-scale decimal strings unless the row is a derived ratio.

## 2026-07-07 income statement fields

| Field                 | Statement          | Description and basis                                                                                                                                                | Refusal / guard behavior                                                                                                                                                                        |
| --------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `interest_expense`    | `income_statement` | Consolidated operating interest expense from the statement face. If the face renders the expense as a negative row, the API serves the canonical positive magnitude. | Refuses `not_reported` when no exact face concept is present. Refuses `ambiguous_candidate` for captive-finance / partial labels or multiple interest-expense-family concepts on the same face. |
| `dividends_per_share` | `income_statement` | Annual common DPS from facts; declared DPS wins, then cash-paid DPS. The overview valuation block exposes the basis as `declared` or `cash_paid`.                    | Refuses `not_reported` when no valid current-FY ISO-4217/share row exists. Refuses `ambiguous_candidate` when class-dimensioned DPS rows differ.                                                |

Both fields still pass through the normal verification masks: a cell can refuse with `verification_pending` while scoring is incomplete or `oracle_contradicted` if verification blocks serving it.


## OpenAPI

````yaml POST /v1/tools/stock_financials
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_financials:
    post:
      tags:
        - Financials
      summary: Get SEC-verified financial statements
      description: >-
        Serves income, balance, cash flow, and ratios from the filer's own
        statements with per-cell provenance. Schema 2 can return a single
        flattened statement or a statements map for multi-statement calls.
      operationId: stock_financials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinancialsRequest'
            examples:
              request:
                summary: Request
                value:
                  symbol: SAP
                  schema: 2
                  statements:
                    - income
                    - balance
                  period_kind: annual
                  periods: 2
      responses:
        '200':
          description: >-
            Get SEC-verified financial statements. 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: '0001000184'
                        name: SAP SE
                        reporting_currency: EUR
                      security:
                        ticker: SAP
                    data:
                      reporting:
                        reporting_currency: EUR
                      statements:
                        income:
                          periods:
                            - label: FY
                              period_end: '2025-12-31'
                              currency: EUR
                          fields:
                            revenue:
                              unit: EUR
                              values:
                                - '37579000000'
                        balance:
                          periods:
                            - label: FY
                              period_end: '2025-12-31'
                              currency: EUR
                          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_financials" \
              -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"symbol":"SAP","schema":2,"statements":["income","balance"],"period_kind":"annual","periods":2}'
components:
  schemas:
    FinancialsRequest:
      type: object
      description: Request body for stock_financials.
      additionalProperties: false
      required:
        - symbol
      properties:
        symbol:
          type: string
          description: Ticker or resolvable symbol.
          minLength: 1
          maxLength: 24
        statement:
          type: string
          enum:
            - income
            - balance
            - cash_flow
            - financials
          description: >-
            Schema-1 statement selector. financials returns all three
            statements.
          default: financials
        period_kind:
          type: string
          enum:
            - annual
            - quarter
            - ytd
          description: Period family to return.
          default: annual
        periods:
          type: integer
          description: Number of periods to return.
          minimum: 1
          maximum: 20
          default: 3
        vintage:
          type: string
          enum:
            - latest_restated
          description: Only latest_restated is advertised and served for new integrations.
          default: latest_restated
        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.
        statements:
          type: array
          description: >-
            Schema-2 statement list. Aliases income_statement and balance_sheet
            are canonicalized before validation; the response orders statements
            as income, balance, cash_flow.
          maxItems: 3
          items:
            type: string
            enum:
              - income
              - balance
              - cash_flow
        approx:
          type: boolean
          description: >-
            Schema-2 only. Adds approximate twin fields when the renderer can
            compute them.
          default: false
    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

````