Getting Started

Jiro is a search intelligence platform that gives you programmatic access to 9 search engines, 12 social platforms, and AI-powered research tools through a single unified API.

There are two deployment options:

Self-Hosted (Free & Open Source) — Install via pip install jirosearch and run on your own infrastructure. You get sliding window rate limiting (5 RPS / 60 RPM / 500/hr / 5K/day on Free tier), 9 search engines (Bing, Google, DuckDuckGo, Brave, YouTube, Amazon, eBay, Yandex, Baidu), 12 social platforms (Reddit, Twitter/X, YouTube, LinkedIn, TikTok, Instagram, Facebook, Threads, Hacker News, Bluesky, Telegram, Pinterest), and 16 MCP tools. No API key required for local development.

Jiro Cloud (Coming Soon) — Managed cloud hosting with pay-per-credit pricing. You get 1,000 free credits per month, all 16 MCP tools, automatic scaling, and zero infrastructure management. Join the waitlist at searchjiro.vercel.app to get early access.

Before installing Jiro, make sure you have the following:

• Python 3.10+ — required for the core server and Python SDK. Check with python --version.
• Node.js 18+ — required for the JavaScript/TypeScript SDK. Check with node --version.
• Go 1.21+ — required for the Go SDK. Check with go version.
• Redis — recommended for caching. Without Redis, caching is disabled and all searches cost full credits. Install via brew install redis, apt install redis, or use a managed Redis instance.
• Git — needed if cloning the repository for Docker or development installs.

For Docker deployments, you only need Docker and Docker Compose installed.

Choose your preferred installation method. All methods give you access to the same API.

Docker (recommended for production):

The Jiro CLI is included with the jirosearch Python package. After installation, verify it works:

bash jiro --version jiro doctor

The jiro doctor command checks your Python version, dependencies, Redis connection, configuration, and package integrity. Run jiro serve to start the API server on http://localhost:8000.

Make your first search request using the CLI, Python SDK, JavaScript SDK, or Go SDK.

Every API response uses a consistent JSON envelope with three top-level fields:

• data — the response payload (null on error)
• error — error details (null on success)
• request_id — unique identifier for tracing and debugging

Successful search response:

When something goes wrong, the error field is populated and data is set to null. Every error has a code, message, and status field:

json { "data": null, "error": { "code": "INVALID_QUERY", "message": "Missing required field: q", "status": 400 }, "request_id": "a1b2c3d4e5f6g7h8" }

Common errors you will encounter:

• 400 INVALID_QUERY — missing or malformed q parameter
• 401 INVALID_API_KEY — missing, malformed, or unknown API key
• 402 INSUFFICIENT_CREDITS — not enough credits for this operation
• 429 USER_RATE_LIMITED — you exceeded your plan's per-minute rate limit
• 502 ENGINE_ERROR — the upstream search engine returned an error (credits refunded)
• 503 ENGINE_UNAVAILABLE — the engine's circuit breaker is open (credits refunded)

Always check the error field before accessing data. Credits are automatically refunded when an error occurs after deduction (engine errors, circuit breaker open).

Each SDK provides built-in error handling:

• [Authentication](/docs/authentication) — learn about API key formats, validation, and security best practices
• [Search](/docs/search) — search across 9 engines with caching and credit costs explained
• [Scrape](/docs/scrape) — extract clean content from any URL
• [AI Search](/docs/ai-search) — agentic AI-powered research with multi-step reasoning
• [Social Platforms](/docs/social-platforms) — scrape 12 social platforms without API keys
• [MCP Setup](/docs/mcp-setup) — connect Jiro to AI coding tools via Model Context Protocol
• [Credits](/docs/credits) — understand the credit system and pricing
• [SDKs & Libraries](/docs/sdks) — detailed SDK usage for Python, JavaScript, and Go