Evidence & provenance

This is the part that makes StockAlloy different. A fact without provenance is a liability in any product whose users might ask “says who?”. Every verified fact in StockAlloy carries an evidence link that resolves to the exact location in the original SEC filing where the value appears.

Span verification

During extraction, every fact is tied back to a byte span in the filing document itself:

1. The value is extracted from the filing’s XBRL/iXBRL structure.
2. The extractor records a locator — for HTML tables, the table fingerprint plus row/column position and character offsets; for iXBRL, the tagged node and context reference.
3. The displayed value at that location in the raw filing HTML is compared against the extracted value. Only facts whose value is verified at its recorded span carry an evidence link.

So an evidence_url isn’t a link to “the filing” — it’s a link to the cell.

The evidence URL

Every fact row’s evidence_url looks like:

https://stockalloy.com/api/evidence/{evidence_id}/open?cik=0001011570&accession=0001011570-24-000039

Opening it redirects (302) to a filing viewer showing the SEC document with the figure highlighted and scrolled into view. The links are stable, public, and safe to place directly in your UI — no API key needed to open them.

Getting the machine-readable payload

When you need the provenance data (not a human-clickable page) — say, to quote the source snippet in an AI answer — use the evidence export:

curl -s https://api.stockalloy.com/api/b2b/evidence/enriched \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STOCKALLOY_API_KEY" \
  -d '{"ticker": "DECK", "metric_id": "us-gaap#RevenueFromContractWithCustomerExcludingAssessedTax"}'

A full evidence row:

{
  "evidence_key": "01HYXR8M3K9W…",
  "cik": "0001011570",
  "source_accession": "0001011570-24-000039",
  "source_form_type": "10-K",
  "source_is_amendment": false,
  "source_filed_at": "2024-05-24",
  "filing_url": "https://stockalloy.com/api/rag/filing-html/0001011570/000101157024000039?lang=en&doc_name=deck-20240331.htm",
  "document_url": "https://www.sec.gov/Archives/edgar/data/1011570/000101157024000039/deck-20240331.htm",
  "evidence_url": "https://stockalloy.com/api/evidence/01HYXR8M3K9W…/open?cik=0001011570&accession=0001011570-24-000039",
  "viewer_url": "https://stockalloy.com/api/rag/filing-html/0001011570/000101157024000039?lang=en&doc_name=deck-20240331.htm&hl_start=1284502&hl_end=1291840",
  "snippet_text": "Net sales … 4,287,763",
  "locator_type": "html",
  "html_start_offset": 1284502,
  "html_end_offset": 1291840,
  "document_name": "deck-20240331.htm",
  "document_sequence": null,
  "section_title": "Consolidated Statements of Comprehensive Income",
  "highlight_payload_json": {
    "locator_type": "html",
    "locator": {
      "type": "html",
      "tableFingerprint": "a91c…",
      "rowIdx": 4,
      "colIdx": 2
    },
    "source_url": "https://www.sec.gov/Archives/edgar/data/1011570/000101157024000039/deck-20240331.htm",
    "viewer_url": "https://stockalloy.com/api/rag/filing-html/0001011570/000101157024000039?…",
    "html_start_offset": 1284502,
    "html_end_offset": 1291840,
    "caption_text": null,
    "section_path": "Part II > Item 8",
    "nearest_heading_text": "Consolidated Statements of Comprehensive Income",
    "table_fingerprint": "a91c…",
    "row_idx": 4,
    "col_idx": 2
  }
}

(Identifiers, offsets, and snippet shortened for readability — shapes are exact.)

What each field gives you:

Field	What it is
evidence_key	Stable ID — joins to evidence_key on fact rows
snippet_text	The source text around the value, for quoting
locator_type	html (table cell), ixbrl (inline-tagged value), or xbrl (instance fact)
html_start_offset / html_end_offset	Character offsets of the containing table in the filing HTML
section_title	Best-effort human label: table caption, nearest heading, or section path
viewer_url	Filing viewer pre-scrolled and highlighted (HTML evidence)
document_url	The original document on sec.gov
highlight_payload_json	Everything the viewer needs to reproduce the highlight — table fingerprint, row/column indexes, iXBRL node and context refs

Rows come back newest filing first. Filter with metric_id to keep payloads small — a full-company evidence export can be large.

Wiring it together

Fact rows and evidence rows share keys:

facts row.evidence_key  ──►  evidence row.evidence_key
facts row.evidence_url  ──►  human-clickable proof (302 to highlighted filing)
evidence row.snippet_text / highlight_payload_json  ──►  machine-readable proof

A typical AI-product pattern:

1. Fetch facts (/api/b2b/facts/full/by-series) and answer with the values.
2. Render each number with its evidence_url as a “verified ✓” link.
3. If the model needs to quote the filing, look up the evidence row and use snippet_text — never let the model paraphrase a number it can’t see.

Optional: tell us when proofs get opened

If you want evidence-open analytics on your own integration (they appear in your portal usage), fire-and-forget:

curl -s https://api.stockalloy.com/api/b2b/telemetry/proof-open \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STOCKALLOY_API_KEY" \
  -d '{"evidence_key": "01HYXR8M3K9W…", "surface": "chat-citation"}'

Returns 202 {"ok": true} immediately and doesn’t count against your monthly quota.