TinyFish Cookbook: Turn Any Website Into an API With Plain English

What if you could point at any website, describe what you want in plain English, and get clean JSON back? No Puppeteer nightmares. No brittle XPath selectors that break every Tuesday. No paying cloud providers $200/month just to render a page in a headless browser.

Every developer has felt this pain. You're building an AI agent that needs live data. The target site has no API. You reach for Playwright, spend three days fighting Cloudflare, rotating proxies, and debugging why that one div loads differently at 2 AM. You ship something fragile, expensive, and fundamentally broken.

There's a better way.

The TinyFish Cookbook is exploding in popularity because it solves exactly this — and the core Search and Fetch endpoints are now completely free. No credit card. No sneaky metered billing on your first 1,000 calls. Just grab a key and start converting the entire web into structured, agent-ready data.

But here's what most developers miss: the Cookbook isn't just documentation. It's a living arsenal of 25+ production recipes — from semiconductor supply chain trackers to Saigon happy hour finders — that show you exactly how to wield this power. Let's pull back the curtain.

What Is the TinyFish Cookbook?

The TinyFish Cookbook is the official open-source collection of sample applications, automation recipes, and integration patterns built on top of TinyFish — a web layer purpose-built for AI agents.

Created by TinyFish AI, the repository serves as both learning material and production boilerplate. Where traditional scraping frameworks give you low-level tools and wish you luck, TinyFish abstracts the entire pipeline: browser automation, proxy rotation, stealth evasion, content cleaning, and structured output — all behind a single API call with a natural-language goal.

Why it's trending now:

• Search and Fetch went free (March 2025) with generous rate limits, removing the biggest friction for experimentation
• MCP server support dropped, letting Claude Code, Cursor, and ChatGPT desktop use TinyFish natively
• Agent Skills launched, enabling one-line installs that teach coding agents when to search, fetch, or run full browser automation
• The repository crossed 1,000+ stars in weeks as developers realized they could stop maintaining scraper infrastructure entirely

The Cookbook reflects this momentum. New recipes land weekly. Each folder is a standalone deployable project with live demos — not toy scripts, but real applications solving real problems.

Key Features That Separate TinyFish From the Scraping Graveyard

Let's dissect what makes this architecture genuinely different from the Firecrawls, Scraplys, and hand-rolled Playwright clusters you've probably abandoned.

Four Endpoint Tiers, One API Key

TinyFish operates on a layered abstraction model — use exactly the power you need, pay only for what you use:

The genius: Most workflows never need Agent or Browser. Search + Fetch handle 80% of production use cases at zero cost.

Token-Efficient Content Cleaning

Fetch doesn't return raw HTML. It strips navigation, scripts, cookie banners, and ads — delivering clean markdown or JSON that doesn't burn your LLM context window on <div class="ad-wrapper__inner--mobile"> noise. This alone can cut token costs 60-80% versus naive fetch-then-parse approaches.

Built-In Stealth Infrastructure

Rotating proxies. Stealth browser profiles. Fingerprint randomization. These aren't premium add-ons — they're included at every tier. TinyFish operates a managed fleet of hardened browsers so you don't become a DevOps engineer for scraper infrastructure.

Vault: Authentication Without Exposure

The Vault system handles credentials via 1Password JIT access and encrypted session reuse. Your agent can log into sites, maintain sessions, and access authenticated data — without you ever touching a password in code.

Production Observability

Every run generates full logs, screenshots, and debugging traces. When an Agent flow fails at 3 AM, you know exactly which step broke and why — not the opaque "timeout" you'd get from a black-box service.

Real-World Use Cases: Where TinyFish Cookbook Recipes Shine

The Cookbook's 25+ recipes aren't theoretical. They're deployed applications solving concrete problems. Here are four patterns that reveal the platform's range:

1. Price Intelligence & Arbitrage

The openbox-deals recipe aggregates real-time open-box and refurbished deals across 8 major retailers — Best Buy, Amazon Warehouse, eBay, and others. It uses parallel browser agents to navigate each site's unique filtering UI, extract structured pricing, and surface true bargains.

Why this matters: Every retailer structures deals differently. Some use infinite scroll, others paginate, others load via JavaScript after a delay. Writing maintainable scrapers for each would be a full-time job. The Agent endpoint handles the variance with natural-language goals.

2. Supply Chain & Procurement Intelligence

silicon-signal tracks semiconductor lifecycle status, availability, and lead times across distributor sites. In an industry where component shortages cost millions, this transforms unstructured distributor web pages into structured procurement signals.

3. Local Discovery & Hyperlocal Commerce

The saigon-happy-hour-sniper finds live happy hour deals across Saigon's bar scene. It navigates Instagram pages, bar websites, and review platforms — sites with no APIs, inconsistent structures, and rapidly changing content.

4. Academic & Research Automation

research-sentry is a voice-first research co-pilot that scans ArXiv, PubMed, and preprint servers. It demonstrates how TinyFish enables multi-source synthesis where no single API provides comprehensive coverage.

Step-by-Step Installation & Setup Guide

Ready to stop reading and start building? Here's the complete path from zero to live API calls.

Step 1: Obtain Your API Key

Navigate to agent.tinyfish.ai and sign up. No credit card required. Your dashboard immediately provides a key with free Search and Fetch access.

# Add to your environment
export TINYFISH_API_KEY="tf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Step 2: Verify With a Test Call

# Free Search endpoint — sub-500ms response
curl "https://api.search.tinyfish.ai?query=web+automation+tools" \
  -H "X-API-Key: $TINYFISH_API_KEY"

Expected: JSON array of ranked results with titles, URLs, and snippets — structured for direct LLM consumption, not human browsing.

Step 3: Install the CLI (Optional but Recommended)

npm install -g @tiny-fish/cli

# Authenticate
tinyfish auth login

# Test drive
tinyfish search query "web automation tools"
tinyfish fetch content get https://example.com

The CLI's critical advantage: it writes results to your filesystem instead of piping through your model's context window. For large extractions, this preserves tokens and keeps outputs structured.

Step 4: Install SDK for Your Language

# Python
pip install tinyfish

# TypeScript / Node.js
npm install @tiny-fish/sdk

Both SDKs provide full parity across all four endpoints plus Vault access.

Step 5: Add the MCP Server (For AI-Native Workflows)

If you use Claude Code, Cursor, Codex, or ChatGPT desktop, add this to your MCP configuration:

{
  "mcpServers": {
    "tinyfish": { "url": "https://mcp.tinyfish.ai" }
  }
}

Your coding agent now has native web access — it decides when to search, when to fetch, and when to deploy full browser automation.

Step 6: Install the Agent Skill

For maximum integration with coding agents:

npx skills add github.com/tinyfish-io/tinyfish-cookbook --skill use-tinyfish

This Skill teaches your agent endpoint selection strategy: Search for broad discovery, Fetch for specific page reading, Agent for multi-step flows. Browse it at skills.sh/tinyfish-io/tinyfish-cookbook/use-tinyfish.

REAL Code Examples From the Repository

Let's examine actual implementations from the TinyFish Cookbook README, with detailed breakdowns of what each accomplishes and how to extend it.

Example 1: REST API — Streaming Agent Execution

The Agent endpoint supports Server-Sent Events (SSE) for real-time progress on long-running automations. Here's the exact cURL from the repository:

curl -N -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://agentql.com",
    "goal": "Find all AgentQL subscription plans and their prices. Return result in json format"
  }'

What's happening here:

• -N disables buffering — critical for SSE streaming
• The goal parameter is pure natural language. No CSS selectors, no DOM paths, no "click the third button" imperative scripts
• TinyFish's agent navigates agentql.com, locates pricing information across potential multiple pages, and returns structured JSON

Production tip: The -N flag is essential. Without it, your client buffers the entire response, defeating the purpose of streaming progress events for long automations.

Example 2: Python SDK — Streaming Response Processing

Here's the repository's Python implementation for the same Agent call:

import json, os, requests

response = requests.post(
    "https://agent.tinyfish.ai/v1/automation/run-sse",
    headers={
        "X-API-Key": os.getenv("TINYFISH_API_KEY"),  # Never hardcode secrets
        "Content-Type": "application/json",
    },
    json={
        "url": "https://agentql.com",
        "goal": "Find all AgentQL subscription plans and their prices. Return result in json format",
    },
    stream=True,  # Enable streaming for real-time updates
)

# SSE format: each line prefixed with "data: "
for line in response.iter_lines():
    if line:
        line_str = line.decode("utf-8")
        if line_str.startswith("data: "):
            # Strip prefix and parse JSON payload
            event = json.loads(line_str[6:])
            print(event)

Key implementation details:

• stream=True is mandatory — without it, you'd wait minutes for the complete response
• The SSE protocol prefixes each event with data: ; the line_str[6:] slice removes this
• Each event contains progress updates: navigation steps, extraction status, partial results, or final structured output

When to extend this pattern: For production systems, replace print(event) with:

• WebSocket broadcasting to frontend clients
• Structured logging to Datadog / Honeycomb
• Checkpoint persistence for resumable long-running flows

Example 3: TypeScript SDK — Modern Async Streaming

The TypeScript implementation leverages modern Web Streams API for identical functionality:

const response = await fetch("https://agent.tinyfish.ai/v1/automation/run-sse", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TINYFISH_API_KEY!,  // Non-null assertion for brevity; validate in production
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://agentql.com",
    goal: "Find all AgentQL subscription plans and their prices. Return result in json format",
  }),
});

// Obtain ReadableStream reader for low-level chunk processing
const reader = response.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;  // Stream complete — agent finished all steps
  
  // Decode Uint8Array chunk to string and process
  console.log(decoder.decode(value));
}

Critical differences from Python:

• Uses native fetch + ReadableStream instead of requests — zero dependencies beyond runtime
• TextDecoder handles UTF-8 decoding of binary chunks; in production, buffer partial multi-byte characters across chunk boundaries
• The ! non-null assertions are for demonstration; production code should validate response.body exists

Advanced pattern: Combine with AbortController for timeout/cancellation:

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 120000); // 2 min max

const response = await fetch(url, { 
  ...options, 
  signal: controller.signal 
});

Example 4: Free Fetch Endpoint — Clean Content Extraction

Before paying for Agent complexity, try if Fetch suffices:

curl -X POST https://api.fetch.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.tinyfish.ai/"]}'

What you get back: Clean markdown with navigation, ads, scripts, and cookie banners stripped. Ready for direct LLM ingestion. Failed URLs cost nothing — you're only charged for successful extractions on metered tiers.

Advanced Usage & Best Practices

Endpoint Selection Heuristics

The Cookbook's Agent Skill encodes this decision tree — internalize it:

1. Search first when you don't know the exact URL
2. Fetch when you have the URL and the page loads statically
3. Agent only when you need interaction: forms, filters, pagination, dynamic content
4. Browser when you have existing Playwright/Selenium scripts to migrate

Parallelization Patterns

The viet-bike-scout recipe demonstrates parallel browser agents — firing multiple Agent calls simultaneously for price comparison across cities. Structure your code for concurrency:

import asyncio

async def compare_prices(cities):
    tasks = [fetch_city_prices(city) for city in cities]
    return await asyncio.gather(*tasks)

Error Handling & Retries

Agent flows can fail mid-navigation. Implement idempotent retries with exponential backoff. The SSE stream includes checkpoint events — design your consumer to resume from last known good state.

Token Optimization

Always prefer Fetch over Agent when possible. The token savings from pre-cleaned content compound across scale. For the tinyskills recipe, which scrapes docs, GitHub, and blogs into unified guides, Fetch's content stripping reduces LLM context costs by an estimated 70% versus raw HTML.

Comparison With Alternatives

The verdict: If you're building AI agents that need web data, TinyFish's natural-language abstraction and free tier create a fundamentally different cost structure. You trade infrastructure control for development velocity — usually the correct trade for agent builders.

FAQ

Is TinyFish really free to start?

Yes. Search and Fetch endpoints are free with generous rate limits, no credit card required. Agent and Browser are metered. Check your dashboard at agent.tinyfish.ai for current quotas.

How does natural-language goal setting actually work?

You describe your objective in plain English (e.g., "Find all subscription plans and prices"). TinyFish's agent interprets this, plans navigation steps, executes them in a managed browser, and returns structured JSON. No DOM knowledge required.

Can I use this with Claude Code or Cursor?

Absolutely. Add the MCP server URL (https://mcp.tinyfish.ai) to your configuration, or install the Agent Skill with npx skills add github.com/tinyfish-io/tinyfish-cookbook --skill use-tinyfish.

What happens when a site blocks automation?

TinyFish includes rotating proxies, stealth browser profiles, and fingerprint randomization. For most sites, this suffices. For extreme cases, the Browser endpoint lets you bring custom evasion techniques.

How do I handle authenticated workflows?

Use the Vault system with 1Password JIT integration. Credentials never touch your code; sessions are encrypted and reusable across agent runs.

Is the Cookbook open for contributions?

Yes — see CONTRIBUTING.md. The team actively merges new recipes and features community projects prominently.

What's the latency for production use?

Search: <500ms. Fetch: 2-5 seconds. Agent: 10 seconds to minutes depending on flow complexity. Browser: real-time interactive. Plan your architecture accordingly — use Search for user-facing latency, Agent for background jobs.

Conclusion: The Web Is Your API Now

The TinyFish Cookbook isn't just another scraping toolkit. It's a fundamental shift in how developers interact with the web — from imperative DOM manipulation to declarative natural-language goals, from infrastructure nightmares to managed abstraction, from metered experimentation to genuinely free tier.

The 25+ recipes prove this isn't vaporware. Production applications are running right now: tracking semiconductors, finding happy hours, comparing motorbike rentals, aggregating open-box deals. Each one converts sites without APIs into structured, agent-consumable data sources.

My take? If you're still maintaining Playwright clusters, fighting Cloudflare, or paying premium rates for basic content extraction, you're working too hard. The free Search and Fetch endpoints remove any excuse not to try this. The Cookbook removes any guesswork about how to build with it.

Your next step: Grab a free key at agent.tinyfish.ai, clone the Cookbook, and run the recipe closest to your use case. The web isn't getting more API-friendly. But with TinyFish, that finally doesn't matter.

Star the repository. Build something impossible yesterday.