DeepSeek Web Intelligence: Search & Fetch APIs

Pricing: \text{Cost} = \0.75 \text{ per } 1,000 \text{ successful requests}$

DeepSeek now offers a suite of tools powered by an internal search engine, designed specifically to empower RAG (Retrieval-Augmented Generation) applications and autonomous agents with real-time internet access.

🛠️ Core Functionality

The system is split into two primary capabilities:

1. Search API: Scans the web for a specific query and provides a structured list of relevant pages.
2. Fetch API: Targets a specific URL to extract its content and convert it into clean Markdown.

---

🔑 Authentication & Connectivity

All requests are routed through the base URL: https://api.deepseek.com.

Required Headers:

[!IMPORTANT] Ensure your API key is kept secure and never exposed in client-side code.

---

🔍 The Search API

Endpoint: POST /v1/tools/search

Request Configuration

To initiate a search, send a JSON body with the following parameters:

• query (String, Required): The search term (1-128 Unicode characters). Cannot be empty or just whitespace.
• count (Integer, Optional): Number of results to return. Range: 1 to 50. Default is 10.
• ori_question (String, Optional): The raw user prompt that led to this search (1-128 chars) to help the engine understand context.
• localization (String, Optional): An IP address to tailor results to a specific region.
• need_content (Boolean, Optional): Set to true to receive the full page content; defaults to false.

Advanced Query Operators

You can refine your search using specific syntax:

Implementation Examples

Using cURL:

curl https://api.deepseek.com/v1/tools/search \
-H Authorization: Bearer YOUR_API_KEY \
-H Content-Type: application/json \
-d '{
  "query": "DeepSeek site:github.com OR site:huggingface.co lang:en after:2025",
  "count": 10
}'

Using Python:

import requests

payload = {
    "query": "DeepSeek V4 release",
    "count": 5,
    "need_content": True
}
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.post("https://api.deepseek.com/v1/tools/search", json=payload, headers=headers)
results = response.json().get("results", [])

for res in results:
    print(f"{res['title']} - {res['url']}\n{res['summary']}\n")

Search Response Schema

A successful response (HTTP 200) returns a results array containing:

• rerank_score (Number): Relevance score from $0 \rightarrow 3$. $\ge 1.5$ is considered high quality.
• snippet (String): A brief summary (100-200 chars) for UI display.
• summary (String): A detailed summary (600-800 chars) optimized for LLM consumption.
• content (String): Full page text (empty if need_content is false).
• site_name / site_icon (String/Null): Metadata about the source website.
• date (String/Null): Publication date in RFC 3339 format.
• authority (Integer): Trust tier from $0 \rightarrow 4$ ($-1$ = unknown). $\ge 3$ is highly authoritative.

---

📄 The Fetch API

Endpoint: POST /v1/tools/fetch

This API is used to retrieve the actual content of a specific page.

Request Fields:

• url (String, Required): The target URL.
  • Max length: 8192 characters.
  • Must be http or https.
  • Must include credentials $\rightarrow$ Must NOT contain usernames or passwords.

Example Request:

import requests

response = requests.post(
    "https://api.deepseek.com/v1/tools/fetch",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": "https://example.com/article"}
)
data = response.json()
print(f"Title: {data['title']}\nContent: {data['content']}")

Response Format:

{
  "title": "Example article",
  "content": "# Example article\n\nArticle content."
}

Note: Fetching depends entirely on the target site's availability and robots.txt or access policies.

---

⚠️ Error Handling

If a request fails, the API returns a structured error object:

{
  "error": {
    "message": "'count' must be between 1 and 50",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request_error"
  }
}

✅ Integration Checklist

• API Key generated and stored in environment variables.
• Request headers set to application/json.
• Search count limited to $\le 50$.
• Fetch URLs validated for HTTP/S and length.
• Error handling implemented for invalid_request_error.