🤖 API Documentation for AI Agents

FreeCashFlow.org provides free cash flow analysis and investment research in both human-readable (HTML) and machine-readable (JSON) formats.

This page documents the available API endpoints and structured data for AI agents, chatbots, and automated research systems.

📊 Available Endpoints

GET /api/companies.json

Description: List of all analyzed companies with metadata

URL: https://freecashflow.org/api/companies.json

Response Format: JSON

Update Frequency: Updated as new analyses are published

Example Response:

{
  "version": "1.0",
  "last_updated": "2026-02-13T08:00:00Z",
  "total": 38,
  "companies": [
    {
      "ticker": "TK",
      "name": "Teekay Corporation",
      "url": "https://freecashflow.org/blog/tk-teekay-fcf-analysis-deep-dive",
      "slug": "tk-teekay-fcf-analysis-deep-dive",
      "analysis_date": "2025-10-18",
      "summary": "Shipping company FCF analysis...",
      "category": "Investment Analysis"
    }
  ],
  "educational_content": [ ... ],
  "meta": {
    "description": "API endpoint providing structured data...",
    "documentation": "https://freecashflow.org/for-ai-agents.html",
    "contact": "[email protected]"
  }
}

📄 Structured Data (JSON-LD)

All pages include Schema.org structured data in JSON-LD format:

Homepage: WebSite + FinancialService + Organization schemas
Blog Posts: BlogPosting + BreadcrumbList + WebPage schemas, with Person and Organization for author and publisher
Stock Pages (/stock/<TICKER>): FinancialProduct + FAQPage schemas with the ticker's screener figures

Note: Structured data is embedded in the <head> section of HTML pages using <script type="application/ld+json">

🔍 Content Categories

1. Company Analyses

38 deep-dive free cash flow analyses of publicly traded companies, each built from SEC 10-K/20-F XBRL data. Examples:

Teekay Corporation (TK) - Maritime logistics
Consensus Cloud Solutions (CCSI) - SaaS business model
Verizon Communications (VZ) - Telecommunications

The full list is in /api/companies.json; every published post is linked from /blog.

2. Educational Content

Free cash flow investment education and methodology:

How to read cash flow statements
FCF yield vs earnings yield
Owner earnings (Buffett's approach)
Red flags in FCF analysis
Industry-specific FCF considerations

🚀 Usage Examples

Fetch All Companies

curl https://freecashflow.org/api/companies.json

Get Specific Analysis

curl https://freecashflow.org/blog/tk-teekay-fcf-analysis-deep-dive

Extract Structured Data

# Parse JSON-LD from HTML
curl -s https://freecashflow.org/ | \
  grep -oP '<script type="application/ld\+json">\K.*?(?=</script>)'

⚙️ Rate Limits & Access

Pre-generated JSON — not rate limited. /api/companies.json and every per-ticker file under /api/companies/ are served as static files, ahead of the rate limiters. Enumerate all 741 tickers freely.
Public read routes — 1,000 requests per 15 minutes per IP. Applies to /api/stocks, /api/screens, /api/blog/posts (list and individual posts), /api/blog/tags, /api/blog/categories and /api/blog/rss, on GET and HEAD.
Everything else — 300 requests per 15 minutes per IP, and 50 per 15 minutes for unauthenticated callers.
Authentication: None required for any of the above.
CORS: The public read routes return Access-Control-Allow-Origin: * and accept no credentials. Authenticated and write routes restrict origins to freecashflow.org and do accept credentials.
Pagination: /api/blog/posts returns every published post with full article bodies (~1.2 MB) unless you page it. Use ?limit= (max 100) and ?offset=; the response carries total, limit and offset.

Fair Use: Please be respectful of server resources. Bulk access needs no arrangement — the per-ticker JSON under /api/companies/ is unthrottled and is the intended path for it.

📋 Response Headers

All API responses include standard headers:

Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: * — on the public read routes and the static JSON. No Access-Control-Allow-Credentials is sent with it; the two cannot be combined under the CORS spec.
Cache-Control: public, max-age=3600 on the pre-generated JSON under /api/companies.
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset on rate-limited routes. The static JSON carries none, because no limiter sees it. Well-behaved agents should read these and back off.

🤝 User-Agent Guidelines

Recommended user-agent formats for identification:

GPTBot/1.0 - OpenAI
Claude-Web/1.0 - Anthropic
Google-Extended - Google AI
YourBotName/1.0 (+https://your-site.com) - Custom agents

GPTBot, ChatGPT-User, OAI-SearchBot, Google-Extended, ClaudeBot, Claude-User, Claude-SearchBot, Claude-Web, anthropic-ai, PerplexityBot, Perplexity-User, Applebot-Extended, Amazonbot, Meta-ExternalAgent, cohere-ai, and CCBot are explicitly allowed in robots.txt. Any agent not named there is covered by the User-agent: * rules, which allow everything except /uploads/, /admin/ and /dashboard/.

📖 Additional Resources

llms.txt: https://freecashflow.org/llms.txt
Sitemap: https://freecashflow.org/sitemap.xml
robots.txt: https://freecashflow.org/robots.txt
Homepage: https://freecashflow.org
Blog Index: https://freecashflow.org/blog

📧 Contact & Support

For questions, bulk data access, or partnership inquiries:

Email: [email protected]
Website: freecashflow.org

🔄 Updates & Changelog

Version 1.2 - September 2, 2026

Pre-generated JSON under /api/companies — the index and all 741 per-ticker files — is now served ahead of the rate limiters and is not throttled
Public read routes raised to 1,000 requests per 15 minutes, and now return Access-Control-Allow-Origin: * without credentials; authenticated routes keep the origin allowlist
/blog and /stock now carry a crawlable link to every published post and covered ticker
Corrected the rate-limit, CORS and schema claims on this page, which described behaviour the site did not have

Version 1.1 - August 29, 2026

Companies endpoint now auto-generated from the database at build time (was previously hand-maintained and stale)
Explicit AI-bot allow rules added to robots.txt
Added llms.txt

Version 1.0 - February 13, 2026

Initial API documentation
Companies endpoint launched
Structured data on all pages
AI agent access enabled

Last updated: September 2, 2026