For Coding Agents

Single-page TinyFish context for Claude, Codex, Cursor, and other coding agents

This page is the shortest high-signal context dump for coding agents integrating TinyFish. Use it when you want one page that explains which API to call, which endpoint to hit, and where to go next for deeper reference.

For complete API reference in a single file, use llms-full.txt (218KB, includes all code examples). Note that llms.txt is just an index — agents should use llms-full.txt for full context.

Choose the Right TinyFish API

API	Use it when	Canonical endpoint	Docs
Agent	You want TinyFish to execute a goal on a real website	POST https://agent.tinyfish.ai/v1/automation/run-sse	Agent reference
Search	You want ranked web results for a query	GET https://api.search.tinyfish.ai	Search overview
Fetch	You want extracted page content from one or more URLs	POST https://api.fetch.tinyfish.ai	Fetch overview
Browser	You want a remote browser session for direct Playwright/CDP control	POST https://api.browser.tinyfish.ai	Browser overview

Quick Decision Tree

• Need data from a URL? — Agent API (goal-based extraction) or Fetch API (raw page content)
• Need search results? — Search API
• Need browser control? — Browser API (direct Playwright/CDP access)

Expected Latency

API	Typical Latency	Suggested Timeout
Agent (sync)	15-60s	120s
Agent (SSE)	15-60s (streaming)	N/A (SSE)
Search	1-3s	10s
Fetch	up to 30s per URL	120s
Browser (create)	10-30s	60s

Authentication

All public REST APIs use the same X-API-Key header.

export TINYFISH_API_KEY="your_api_key_here"

Get a key from agent.tinyfish.ai/api-keys. See Authentication for the full setup and error handling details.

Minimum Viable Example (Python SDK)

from tinyfish import TinyFish, CompleteEvent

client = TinyFish()

with client.agent.stream(
    url="https://example.com",
    goal="Extract the page title. Return as JSON.",
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            print(event.result_json)

Minimal Request Examples (cURL)

Agent

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://scrapeme.live/shop",
    "goal": "Extract the first 2 product names and prices. Return JSON."
  }'

Search

curl "https://api.search.tinyfish.ai?query=web+automation+tools&location=US&language=en" \
  -H "X-API-Key: $TINYFISH_API_KEY"

Fetch

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/"]}'

Browser

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

Prompting

Goal quality determines success rate. Vague goals like “get the data” fail; crafted goals with explicit fields, output format, and edge-case handling succeed consistently.

See the full Prompting Guide for tested patterns, templates, and examples.

Common Gotchas

1. Browser API session creation takes 10-30s — set timeout=60 on your HTTP client.
2. TypeScript needs "type": "module" in package.json for top-level await, or wrap code in async function main() { ... }; main().
3. COMPLETED status does not mean the goal succeeded — always check result_json for failure signals like “captcha”, “blocked”, or “access denied”.
4. Fetch API has a 30s per-URL backend timeout — set your client timeout to 120s for batch requests with multiple URLs.

What to Read Next

Agent reference

Goal-based automation, endpoint choice, runs, profiles, and proxies

Authentication

API key setup and troubleshooting

Search overview

Search query parameters and result shape

Fetch overview

Fetch multiple URLs and choose output formats

Browser overview

Create a remote browser session and connect via CDP

Examples

Copy-paste examples for common workflows

llms-full.txt

Complete API reference in a single file (218KB)