Extract a 10-K risk-factor section with source context · SEC API

WHAT YOU WILL BUILD

Resolve the annual report’s actual primary filename, ask for Item1A, and inspect the extraction method and pagination. Treat the result as a heuristic section candidate that needs source review.

Requirements: Node.js 22 or later; no extra packages. An API key from your dashboard, stored in the SEC_API_KEY environment variable.

Run the workflow

Save this as workflow.mjs and run node workflow.mjs. The production base URL is used by default. Keep credentials out of source control.

// Node.js 22+. Set SEC_API_KEY before running.
const key = process.env.SEC_API_KEY;
if (!key) throw new Error("Set SEC_API_KEY first");
const base = process.env.SEC_API_BASE_URL || "https://sec-api.dev";
async function request(path) {
  const response = await fetch(base + path, {
    headers: { Authorization: "Bearer " + key }
  });
  if (!response.ok) {
    throw new Error("HTTP " + response.status + ": " + await response.text());
  }
  return response.json();
}
const filings = await request("/api/v1/filings?" + new URLSearchParams({
  cik: "320193", form: "10-K", limit: "1"
}));
if (!filings.data.length) throw new Error("No matching recent filing");
const filing = filings.data[0];
const identity = { cik: "320193", accession: filing.accessionNumber };

const result = await request("/api/v1/extract?" + new URLSearchParams({
  ...identity, document: filing.primaryDocument, form: "10-K", section: "1A", limit: "20000"
}));
console.log(JSON.stringify({section: result.data.section,
  method: result.data.boundaryMethod, candidates: result.data.candidateCount,
  text: result.data.text, pagination: result.pagination, source: result.meta}, null, 2));

Make the requested section explicit

This workflow selects a10-K and asks for Item1A. Section identifiers are form-specific. For a10-Q, the contract also requires its part, because repeated item numbers occur across parts. Do not blindly reuse an annual-report section identifier for a current report or quarterly filing. A mismatched source form or unsupported item should fail visibly.

Audit the boundary decision

The extraction method uses headings, and filings have varied layouts. Tables of contents, repeated headers, and unusual markup can make boundaries ambiguous. Retain boundaryMethod and candidateCount with the text. If the endpoint reports unreliable boundaries, use the document-text endpoint and inspect the source instead of telling a user that no risk factors exist. This is narrative extraction, not an accounting normalization engine.

Avoid truncating your analysis silently

The request is capped at20,000characters. Check the returned pagination before summarizing or comparing sections. A partial section must be labeled partial. If you later compare several years, preserve accession and filing dates for every sample, including amendments. The API does not decide whether changes in wording are material to an investment decision.

Sources and further reading

The underlying SEC dataset behavior is documented in the official SEC API reference and SEC technical specifications. Response-field names shown here belong to the sec-api.dev endpoint contract. The scripts print actual results and do not embed fabricated filing or financial data.

All tutorials ←