Schema 2 refusals and provenance

{ "unavailable": "not_reported" }

{
  "unavailable": "valuation_operand_unavailable",
  "missing_operand": "shares_outstanding",
  "affects": ["market_cap", "price_to_book"],
  "recovery": { "action": "none", "note": "shares_outstanding is a data gap we own; no caller action serves it" }
}

curl -sS "https://api.stockcontext.com/v1/tools/stock_overview" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"RIVN","detail":"core"}'

{
  "data": {
    "snapshot": {
      "period": "FY2025",
      "price": { "close": 17.18, "session": "2026-07-01" },
      "revenue": { "v": "5387000000", "d": "≈$5.387B" },
      "net_income": { "v": "-3646000000", "d": "≈-$3.646B" },
      "shares_outstanding": { "unavailable": "not_reported" }
    },
    "valuation": {
      "block_refusal": {
        "unavailable": "valuation_operand_unavailable",
        "recovery": {
          "action": "none",
          "note": "shares_outstanding is a data gap we own; no caller action serves it"
        },
        "missing_operand": "shares_outstanding",
        "affects": [
          "market_cap",
          "price_to_book",
          "price_to_sales",
          "enterprise_value",
          "ev_to_sales",
          "earnings_yield_pct",
          "book_value_per_share",
          "fcf_per_share"
        ]
      },
      "price_to_earnings": { "unavailable": "ratio_undefined_nonpositive_denominator" },
      "price_to_fcf": { "unavailable": "ratio_undefined_nonpositive_denominator" },
      "dividend_yield_pct": { "unavailable": "valuation_operand_unavailable", "missing_operand": "dividends_paid" }
    }
  }
}

curl -sS "https://api.stockcontext.com/v1/tools/stock_reference" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog":"refusal_reasons"}'

{
  "data": {
    "catalog": "refusal_reasons",
    "items": [
      {
        "token": "ingestion_pending",
        "meaning": "This company is known but its filings are not ingested yet; retry later.",
        "recovery": [
          { "action": "retry", "requires": ["retry_after_s"] },
          { "action": "none" }
        ]
      },
      {
        "token": "interim_not_filed_with_sec",
        "meaning": "The filer files no interim (10-Q) reports with the SEC, so no quarterly fundamentals exist to serve — a fact about the filer (a 20-F/40-F foreign private issuer publishes interim results only as unstructured 6-K narrative, never as sub-annual XBRL), not a coverage gap.",
        "recovery": [{ "action": "none" }]
      },
      {
        "token": "invalid_request",
        "meaning": "The request failed parameter validation. errors[] names each offending param with what was given and what is expected; the recovery carries a literal corrected params fragment whenever one can be honestly derived (alias canonicalization or a documented default).",
        "recovery": [
          { "action": "supply_params", "requires": ["params"] },
          { "action": "none" }
        ]
      },
      {
        "token": "not_applicable_for_shape",
        "meaning": "The statement shape structurally lacks this line, distinct from a filer-specific not_reported omission; use the named shape-native analog when the recovery provides one.",
        "recovery": [
          { "action": "use_alternative_field", "requires": ["field"] },
          { "action": "none" }
        ]
      }
    ]
  },
  "meta": { "schema_version": "2" }
}

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

{
  "data": {
    "statement": "income_statement",
    "shape": "operating_company",
    "periods": [{ "id": "FY2025", "start": "2024-09-29", "end": "2025-09-27", "restated": false }],
    "source": { "form": "10-K", "accession": "0001067983-25-000123", "filed": "2025-10-31" },
    "fields": {
      "revenue": ["416161000000"],
      "net_income": ["112010000000"],
      "eps_diluted": [{ "v": "7.46", "source_class": "doc_extracted" }]
    },
    "unavailable_fields": {
      "operating_income": {
        "unavailable": "verification_pending",
        "recovery": { "action": "retry", "retry_after_s": 3600 }
      }
    }
  },
  "meta": { "schema_version": "2", "as_of": { "sec": "2025-10-31" } }
}