tinyfish-sdk

name	tinyfish-sdk
description	Teaches the agent how to use Tinyfish's REST Search and Fetch APIs from TypeScript/JavaScript. Use when you need lightweight web search, documentation fetching, or GitHub PR page retrieval without launching Playwright or AgentQL.

Tinyfish REST APIs

Use this skill when you need Tinyfish-backed search or page fetching in this repo.

Preferred Approach in This Project

Use the workspace client:

import { TinyfishClient } from '@agsk/lib-tinyfish';

This client talks directly to Tinyfish's REST APIs with native fetch() and does not launch a browser locally.

Setup

export TINYFISH_API_KEY="your_api_key"

No Playwright, Chromium, or AgentQL setup is required.

APIs Used Here

Search API

GET https://api.search.tinyfish.ai?query=<query>&location=US&language=en
X-API-Key: <your_api_key>

Response shape:

interface TinyfishSearchResult {
  position: number;
  site_name: string;
  title: string;
  snippet: string;
  url: string;
}

Fetch API

POST https://api.fetch.tinyfish.ai
X-API-Key: <your_api_key>
Content-Type: application/json

{
  "urls": ["https://example.com/docs"],
  "format": "markdown"
}

Response shape:

interface TinyfishFetchResult {
  url: string;
  final_url: string;
  title: string | null;
  description: string | null;
  language: string | null;
  text: string;
  format: 'markdown' | 'html' | 'json';
  response_time_ms: number | null;
}

Usage: Search

import { TinyfishClient } from '@agsk/lib-tinyfish';

const client = new TinyfishClient({
  apiKey: process.env.TINYFISH_API_KEY!,
});

const response = await client.search('express error handling typescript docs');

for (const result of response.results.slice(0, 3)) {
  console.log(result.title, result.url);
}

Notes:

• search() uses a built-in 5s timeout
• You may also pass signal to cancel earlier
• Keep calls sparse because Search is rate-limited more tightly than Fetch

Usage: Fetch

import { TinyfishClient } from '@agsk/lib-tinyfish';

const client = new TinyfishClient({
  apiKey: process.env.TINYFISH_API_KEY!,
});

const response = await client.fetch([
  'https://expressjs.com/en/guide/error-handling.html',
  'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise',
]);

for (const page of response.results) {
  console.log(page.title);
  console.log(page.text.slice(0, 400));
}

Notes:

• fetch() uses a built-in 15s timeout
• Fetch accepts up to 10 URLs per request
• Default format is markdown

Usage: GitHub Pull Request Page Fetch

const markdown = await client.fetchGitHubPR(
  'https://github.com/owner/repo/pull/123',
);

console.log(markdown);

This is useful when you want the rendered PR page as LLM-ready markdown.

Best Practices

• Prefer 1 search call + 1 batched fetch call when enriching review context
• Search first, then fetch only the top 2-3 most relevant URLs
• Prefer official docs, MDN, GitHub, and package registry pages when choosing URLs
• Treat Tinyfish failures as non-fatal in review flows; return partial context when possible
• Gate usage on TINYFISH_API_KEY and skip gracefully when missing

Repo-Specific Guidance

In pi-reviewer, Tinyfish is used to enrich review prompts with:

• code-pattern searches from diffs
• fetched documentation excerpts
• optional GitHub PR page context

The enrichment flow must stay fail-safe and must never block or kill the core review pipeline.