> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TinyFish

> Search, fetch, and automate the web with TinyFish web agents

## Overview

TinyFish tools provide web infrastructure for AI agents: structured web search, full-browser page fetching, and a natural-language browser agent that navigates real websites and extracts structured data.

## Key Features

* `TINYFISH_SEARCH`
  * Search the web with a query string and get structured JSON results (title, URL, description, snippet)
  * Control the number of results (`num_results`, 1–50, default 10) and geo-target results with a two-letter country code (`country`, e.g. `us`, `jp`)
* `TINYFISH_FETCH`
  * Render and extract clean content from one or more URLs using a full browser — works on JavaScript-heavy pages
  * Pass a single URL string or a JSON array of URLs (`urls`), and choose the output format (`format`: `markdown` (default), `html`, `json`, or `text`)
* `TINYFISH_AGENT`
  * Run a browser automation agent: give it a starting URL (`url`) and a natural-language goal (`goal`), and it navigates the site and extracts structured data
  * Configure the maximum run time with `timeout_seconds` (default 300)
  * Returns the stream of agent events plus the final result

## Authentication

All TinyFish tools authenticate with a TinyFish API key, set via the `api_key` config (stored as a secret). If the config is not provided, the tools fall back to the `TINYFISH_API_KEY` environment variable.

**Note**: Treat API keys as sensitive information and never commit them to public repositories.

## Usage Examples

### Example: Search the web and fetch the top pages

```yaml theme={null}
- id: search_news
  name: search_news
  tool: TINYFISH_SEARCH
  config:
    - name: api_key
      value: "{{secrets.TINYFISH_API_KEY}}"
  input:
    - name: query
      value: latest AI workflow automation trends
    - name: num_results
      value: 5
    - name: country
      value: us
- id: fetch_pages
  name: fetch_pages
  tool: TINYFISH_FETCH
  config:
    - name: api_key
      value: "{{secrets.TINYFISH_API_KEY}}"
  input:
    - name: urls
      value: '["https://example.com/article-1","https://example.com/article-2"]'
    - name: format
      value: markdown
```

### Example: Extract structured data with the browser agent

```yaml theme={null}
- id: check_pricing
  name: check_pricing
  tool: TINYFISH_AGENT
  config:
    - name: api_key
      value: "{{secrets.TINYFISH_API_KEY}}"
  input:
    - name: url
      value: https://example.com/pricing
    - name: goal
      value: Find all subscription plans and prices. Return JSON.
    - name: timeout_seconds
      value: 300
```

## Notes

* `TINYFISH_AGENT` is an at-least-once operation: if a worker dies mid-run, the runner may resubmit the job. Avoid using it for irreversible side effects (form submissions, purchases, etc.) without an external idempotency guard.
* `TINYFISH_FETCH` accepts `urls` as a single URL string, a comma-separated list, or a JSON array.
* `TINYFISH_SEARCH` returns at most 50 results per call.