filingstudio-proxy

Server-side proxy for Filing Studio on FastAPI. Your API key stays on your server; the browser talks only to your route. This is the Python twin of @filingstudio/proxy (Next.js and Express), with the same contract, so @filingstudio/react works unchanged in front of it.

pip install filingstudio-proxy

import os
from fastapi import FastAPI
from filingstudio_proxy import filing_studio_router

app = FastAPI()
app.include_router(
    filing_studio_router(api_key=os.environ["FILING_STUDIO_API_KEY"]),
    prefix="/api/filings",
)

Then in the browser: <ProvenanceProvider proxy="/api/filings">.

Public demo? Cap each visitor

filing_studio_router(api_key=key, budget=40)   # 40 metered requests per visitor per day

Over budget the route answers 429 with an honest note the drawer shows ("Daily demo limit reached… This says nothing about what the filings contain"), never a fake "not found". Coverage checks are never metered, and cached answers are served before the meter, so reopening a receipt is free.

Meter on your own login instead of the visitor IP:

filing_studio_router(
    api_key=key,
    budget=100,
    visitor_key=lambda req: req.state.user_id,
    limit_for=lambda req: req.state.daily_limit,   # optional per-user quota
)

Share links

app.include_router(filing_studio_router(KEY, share=True), prefix="/api/filings")
# POST /api/filings/share  {kind: "research" | "receipt", ...}  -> 201 {id, path}
# GET  /api/filings/share/{id}                                 -> the snapshot

Creation is metered and can be gated (ShareOptions(allow=...)); reads are public and cacheable. ShareOptions(store=...) takes any object with create(snapshot, request) -> id and read(id, request); the default is in memory, capped at 1,000.

What it guarantees

• Only GET and POST, only to an allowlist of /v1 read paths. Dot segments and backslashes are refused before allowlisting.
• Nothing from the browser request is forwarded except the /v1 path, its query string, and a POST body (capped at 64 KB).
• Successful GETs are cached in-process (one hour by default) and served before the meter. Errors are never cached.
• The reply carries X-FS-Demo-Remaining when metered; the React SDK's onLimit reads it.
• A missing key answers 503; an unreachable upstream answers 502. Neither message can contain the key.

Options

Develop

pip install -e .[test]
pytest

MIT