Build with FilingSift.

Install and prepare

python -m pip install filingsift==0.2.0
npm install @filingsift/client@0.2.0

Use Python 3.10+ or Node.js 20+ with fetch and AbortSignal.timeout. These are server-side examples. Follow account and API-key setup, grant filings:read and search:read, and supply FILINGSIFT_API_KEY through your process secret environment. Choose a ticker accessible to your organization with indexed filings; AAPL below is an example, not a coverage guarantee.

Each tutorial makes one search request and at most two filing-list requests. Each request uses your existing allowance. To try a public request without a key, initialize the client without credentials and call get_company("AAPL") in Python or getCompany("AAPL") in JavaScript.

Python: search and paginate filings

Save as example.py and run python example.py after installation and secret setup.

import os
from filingsift import FilingSiftClient, FilingSiftError

client = FilingSiftClient(api_key=os.environ["FILINGSIFT_API_KEY"], timeout=15)
try:
    search = client.request("POST", "/search", json_body={
        "query": "debt", "limit": 5, "useSynonyms": True,
        "filters": {"tickers": ["AAPL"], "forms": ["10-Q"]}
    })
    print(search["data"]["results"])  # Keep each match's evidence and provenance.

    # Search is bounded, not cursor-paginated. Filing lists support cursors.
    filters = {"ticker": "AAPL", "form": "10-Q", "limit": 2}
    cursor = None
    for _ in range(2):  # At most two pages for this example, not a bulk download.
        page = client.request("GET", "/filings", query={**filters, "cursor": cursor})
        print(page["data"])
        pagination = page["meta"]["pagination"]
        if not pagination["hasMore"]:
            break
        cursor = pagination["nextCursor"]
except FilingSiftError as error:
    print("Request failed:", error.status, error.code, error.request_id)
    raise  # Resolve the cause before retrying; do not log credentials.
except (TimeoutError, OSError):
    print("Connection or timeout failure; check connectivity before retrying.")
    raise

Download the Python source client or public Jupyter notebook.

TypeScript and Node.js: search and paginate filings

The package includes TypeScript declarations. This runnable ESM example also works as JavaScript: save it as example.mjs and run node example.mjs.

import { FilingSiftClient, FilingSiftError } from "@filingsift/client";

const apiKey = process.env.FILINGSIFT_API_KEY;
if (!apiKey) throw new Error("Set FILINGSIFT_API_KEY in your server environment");
const client = new FilingSiftClient({ apiKey, timeoutMs: 15_000 });
try {
  const search = await client.request("POST", "/search", { body: {
    query: "debt", limit: 5, useSynonyms: true,
    filters: { tickers: ["AAPL"], forms: ["10-Q"] }
  }});
  console.log(search.data.results); // Keep each match's evidence and provenance.

  // Search is bounded, not cursor-paginated. Filing lists support cursors.
  const filters = { ticker: "AAPL", form: "10-Q", limit: 2 };
  let cursor;
  for (let pageNumber = 0; pageNumber < 2; pageNumber++) {
    const page = await client.request("GET", "/filings", {
      query: { ...filters, cursor }
    });
    console.log(page.data);
    if (!page.meta.pagination.hasMore) break;
    cursor = page.meta.pagination.nextCursor;
  }
} catch (error) {
  if (error instanceof FilingSiftError) {
    console.error("Request failed:", error.status, error.code, error.requestId);
  }
  throw error; // Resolve the cause before retrying; do not log credentials.
}

Download the JavaScript runtime and TypeScript declarations.

Pagination and search boundaries

Filing lists return meta.pagination.hasMore and nextCursor. Pass the opaque cursor unchanged with the same filters. The examples intentionally stop after two pages; a production job should also enforce a request budget. If invalid_cursor occurs, restart the listing and deduplicate records already handled. The POST /search tutorial returns bounded data.results and a truncated flag, not a next-page cursor. The website instead uses POST /search/market, with continuation in data.pagination; for the bounded tutorial, narrow the ticker, form or date filters when results are truncated.

Responses, errors and safe retries

• Every filing-derived fact retains accession, source URL, evidence and verification state. Keep those fields together.
• Unavailable values remain unavailable and are never converted to zero. Empty results can reflect indexed coverage or account boundaries.
• JSON envelopes are returned unchanged; text is a string, PDF/XLSX is bytes in Python or Uint8Array in JavaScript. Successful HTTP 204/205 returns None or null.
• Structured errors expose status, code and request ID. Use the troubleshooting guide before retrying.
• The SDKs do not automatically paginate, retry or reconnect streams. Never blindly retry a mutation after a client error; inspect current resource state first.
• Successful response headers are not exposed by these SDK versions; use a lower-level HTTP client when you need checksum or rate-limit headers.
• Saved searches, annotations, folders and other browser-session-only workflows require the signed-in website. An SDK helper does not grant permission.

Contract references

See the REST API documentation, MCP connection guide, OpenAPI specification, comparison workflow and factual API case study.