Jina AI — Reader, Search & DeepSearch

Web reading and search powered by Jina AI. Requires JINA_API_KEY environment variable.

Trust & Privacy: By using this skill, URLs and queries are transmitted to Jina AI (jina.ai). Only install if you trust Jina with your data.

Model Invocation: This skill may be invoked autonomously by the model without explicit user trigger (standard for integration skills). If you prefer manual-only invocation, disable model invocation in your OpenClaw skill settings.

Get your API key: https://jina.ai/ → Dashboard → API Keys

External Endpoints

This skill makes HTTP requests to the following external endpoints only:

Endpoint	URL Pattern	Purpose
Reader API	https://r.jina.ai/{url}	Sends URL content request to Jina for conversion to markdown
Search API	https://s.jina.ai/{query}	Sends search query to Jina for web search results
DeepSearch API	https://deepsearch.jina.ai/v1/chat/completions	Sends research question to Jina for multi-step research

No other external network calls are made by this skill.

Security & Privacy

• Authentication: Only your JINA_API_KEY is transmitted to Jina's servers (via Authorization header)
• Data sent: URLs and search queries you provide are sent to Jina's servers for processing
• Local files: No local files are read or transmitted by this skill
• Local storage: No data is stored locally beyond stdout output
• Environment access: Scripts only access the JINA_API_KEY environment variable; no other env vars are read
• Cookies: Cookies are not forwarded by default; the X-Set-Cookie header is available for authenticated content but is opt-in only

Endpoints

Endpoint	Base URL	Purpose
Reader	https://r.jina.ai/{url}	Convert any URL → clean markdown
Search	https://s.jina.ai/{query}	Web search with LLM-friendly results
DeepSearch	https://deepsearch.jina.ai/v1/chat/completions	Multi-step research agent

All endpoints accept Authorization: Bearer $JINA_API_KEY.

---

Reader API (r.jina.ai)

Fetches any URL and returns clean, LLM-friendly content. Works with web pages, PDFs, and JS-heavy sites.

Basic Usage

# Plain text output
curl -s "https://r.jina.ai/https://example.com" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "Accept: text/plain"

# JSON output (includes url, title, content, timestamp)
curl -s "https://r.jina.ai/https://example.com" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "Accept: application/json"

Or use the helper script: scripts/jina-reader.sh <url> [--json]

Parameters (via headers or query params)

Content Control

Header	Query Param	Values	Default	Description
X-Respond-With	respondWith	content, markdown, html, text, screenshot, pageshot, vlm, readerlm-v2	content	Output format
X-Retain-Images	retainImages	none, all, alt, all_p, alt_p	all	Image handling
X-Retain-Links	retainLinks	none, all, text, gpt-oss	all	Link handling
X-With-Generated-Alt	withGeneratedAlt	true/false	false	Auto-caption images
X-With-Links-Summary	withLinksSummary	true	-	Append links section
X-With-Images-Summary	withImagesSummary	true/false	false	Append images section
X-Token-Budget	tokenBudget	number	-	Max tokens for response

CSS Selectors

Header	Query Param	Description
X-Target-Selector	targetSelector	Only extract matching elements
X-Wait-For-Selector	waitForSelector	Wait for elements before extracting
X-Remove-Selector	removeSelector	Remove elements before extraction

Browser & Network

Header	Query Param	Description
X-Timeout	timeout	Page load timeout (1-180s)
X-Respond-Timing	respondTiming	When page is "ready" (html, network-idle, etc.)
X-No-Cache	noCache	Bypass cached content
X-Proxy	proxy	Country code or auto for proxy
X-Set-Cookie	setCookies	Forward cookies for authenticated content

Common Patterns

# Extract main content, remove navigation elements
curl -s "https://r.jina.ai/https://example.com/article" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "X-Retain-Images: none" \
  -H "X-Remove-Selector: nav, footer, .sidebar, .ads" \
  -H "Accept: text/plain"

# Extract specific section
curl -s "https://r.jina.ai/https://example.com" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "X-Target-Selector: article.main-content"

# Parse a PDF
curl -s "https://r.jina.ai/https://example.com/paper.pdf" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "Accept: text/plain"

# Wait for dynamic content
curl -s "https://r.jina.ai/https://spa-app.com" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "X-Wait-For-Selector: .loaded-content" \
  -H "X-Respond-Timing: network-idle"

---

Search API (s.jina.ai)

Web search returning LLM-friendly results with full page content.

Basic Usage

# Plain text
curl -s "https://s.jina.ai/your+search+query" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "Accept: text/plain"

# JSON
curl -s "https://s.jina.ai/your+search+query" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "Accept: application/json"

Or use the helper script: scripts/jina-search.sh "<query>" [--json]

Search Parameters

Param	Values	Description
site	domain	Limit to specific site
type	web, images, news	Search type
num / count	0-20	Number of results
gl	country code	Geo-location (e.g. us, in)
filetype	extension	Filter by file type
intitle	string	Must appear in title

All Reader parameters also work on search results.

Common Patterns

# Site-scoped search
curl -s "https://s.jina.ai/OpenAI+GPT-5?site=reddit.com" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "Accept: text/plain"

# News search
curl -s "https://s.jina.ai/latest+AI+news?type=news&num=5" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "Accept: application/json"

# Search for PDFs
curl -s "https://s.jina.ai/machine+learning+survey?filetype=pdf&num=5" \
  -H "Authorization: Bearer $JINA_API_KEY"

---

DeepSearch

Multi-step research agent that combines search + reading + reasoning. OpenAI-compatible chat completions API.

curl -s "https://deepsearch.jina.ai/v1/chat/completions" \
  -H "Authorization: Bearer $JINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-deepsearch-v1",
    "messages": [{"role": "user", "content": "Your research question here"}],
    "stream": false
  }'

Or use the helper script: scripts/jina-deepsearch.sh "<question>"

Use for complex research requiring multiple sources and reasoning chains.

---

Helper Scripts

Script	Purpose
scripts/jina-reader.sh	Read any URL as markdown
scripts/jina-search.sh	Web search
scripts/jina-deepsearch.sh	Deep multi-step research
scripts/jina-reader.py	Python reader (no deps beyond stdlib)

---

Rate Limits

• Free (no key): 20 RPM
• With API key: Higher limits, token-based pricing

API Docs

• Reader: https://jina.ai/reader
• Search: https://s.jina.ai/docs
• OpenAPI specs: https://r.jina.ai/openapi.json | https://s.jina.ai/openapi.json

When to Use

Need	Use
Fetch a URL as markdown	Reader — better than web_fetch for JS-heavy sites
Web search	Search — LLM-friendly results
Complex multi-source research	DeepSearch
Parse a PDF from URL	Reader — pass PDF URL directly
Screenshot a page	Reader with X-Respond-With: screenshot
Extract structured data	Reader with jsonSchema param