API Reference

The FolioFact REST API v1 is a read-only JSON API over the same public research data as the website: tracked funds, their quarterly 13F filings and holdings, the stocks they own, investor portfolios, and the cross-fund insider feed. It is fully documented in /openapi.yaml (OpenAPI 3.1) — the machine contract every agent should read first. This page is the human quick-start.

Authentication

Two ways to call the API:

• Anonymous — no key needed; public data with the anonymous rate limits (20 req/min, 1,000 req/day per IP).
• API key — Authorization: Bearer ff_… (or X-Api-Key: ff_…). Keys are created in Settings → API keys, inherit your account's plan, and are revocable at any time. Pro subscribers unlock the gated endpoints below.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Hitting a limit returns 429 with a Retry-After header.

Endpoints

Method Path Access GET /api/v1/meta public GET /api/v1/search?q= public GET /api/v1/funds public GET /api/v1/funds/:slug public GET /api/v1/funds/:slug/holdings public GET /api/v1/funds/:slug/history public GET /api/v1/stocks public GET /api/v1/stocks/:ticker public GET /api/v1/stocks/:ticker/financials Pro GET /api/v1/stocks/:ticker/insiders Pro GET /api/v1/stocks/:ticker/options Pro GET /api/v1/investors public GET /api/v1/investors/:slug public GET /api/v1/insiders (deep pages Pro) public GET /api/v1/insiders?format=csv Pro GET /api/v1/compare?tickers=AAPL,MSFT Pro

Example requests

# Catalog + your tier
curl -H "Accept: application/json" https://foliofact.com/api/v1/meta

# Public search
curl -H "Accept: application/json" "https://foliofact.com/api/v1/search?q=pabrai"

# With a key (Pro example)
curl -H "Accept: application/json" \
     -H "Authorization: Bearer ff_YOUR_KEY" \
     https://foliofact.com/api/v1/stocks/AAPL/financials

Errors

Errors are JSON with a stable shape:

{ "error": { "code": "tier_required", "message": "…", "tier_hint": "…", "docs_url": "…" } }

Stable codes are invalid_pagination (400), invalid_api_key (401), tier_required (403 → /pricing), resource_not_found (404), json_only (406), invalid_compare (422), and rate_limited (429).

Stability promise

v1 is additive-only. New endpoints and fields may be added at any time; breaking changes ship as v2. See docs/api_stability.md.