Download annual reports as markdown

Discover and fetch only advertised links

Install httpx and set STOCKMARKET_API_KEY. This example requests ASX filings for an illustrative company, skips missing conversions, validates the download host before sending a credential, and checks each HTTP status.

import os
from urllib.parse import urlparse
import httpx

headers = {"X-API-Key": os.environ["STOCKMARKET_API_KEY"]}
with httpx.Client(timeout=30) as client:
    response = client.get(
        "https://stockmarketapi.ai/api/v1/companies/BHP/filings",
        params={"source": "asx", "limit": 3, "exchange": "ASX"},
        headers=headers,
    )
    response.raise_for_status()
    for filing in response.json()["filings"]:
        url = filing.get("markdown_url")
        if not url:
            continue
        # Only send the API key to the API's own download host.
        parsed = urlparse(url)
        if parsed.scheme != "https" or parsed.netloc != "stockmarketapi.ai":
            continue
        document = client.get(url, headers=headers)
        document.raise_for_status()
        print(filing.get("report_date"), document.text[:500])

Keep the document identity

Save source, accession_number, form_type, report_date, filing_date, and document_url alongside extracted text. report_date is a period-end label; filing_date is the release date and may be null. Keep stable links instead of storing optional short-lived storage redirects.

Verify content before indexing

A conversion can change table structure, omit scanned text, or distort footnotes. Compare representative text and tables with the PDF before using the markdown in a retrieval system. An empty filings list and a list of PDFs without markdown are different ingestion states and should be reported separately.

• Download contract →
• Markdown capability →