菜单
Query the Read the Docs Search API to find documentation across projects and repositories. Use when searching documentation, finding related docs, finding API documentation, or gathering information about projects on Read the Docs.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | readthedocs-search-api |
| description | Query the Read the Docs Search API to find documentation across projects and repositories. Use when searching documentation, finding related docs, finding API documentation, or gathering information about projects on Read the Docs. |
| metadata | {"source":"https://docs.readthedocs.com/platform/stable/server-side-search/api.html"} |
Query the public Read the Docs Search API to find documentation across millions of pages. This API is available on both Community and Business sites; the base URL changes by host.
Set RTD_HOST for your site:
https://app.readthedocs.orghttps://app.readthedocs.comQuery the API using:
GET ${RTD_HOST}/api/v3/search/?q={query}&page={page}
Required parameters:
q: Your search query (e.g., "authentication", "API pagination")page: Result page number (default: 1)Note on scoping: You will generally get better and more consistent results by scoping your query to a specific project. Use fielded search syntax inside q, for example project:{project-slug} your terms.
Examples: project:docs build, project:sphinx configuration.
The API returns JSON with this structure:
{
"count": 1234,
"next": "https://readthedocs.org/api/v3/search/?q=query&page=2",
"previous": null,
"results": [
{
"id": "project-name:doc-title",
"project": "project-name",
"version": "latest",
"title": "Documentation Title",
"path": "/en/latest/path/to/page.html",
"domain": "project-name.readthedocs.io",
"highlight": "snippet of matching <mark>text</mark>...",
"blocks": [
{
"id": "section-id",
"title": "Section Title",
"path": "/path#section-id"
}
]
}
]
}
If there are more results, use the next URL to fetch the next page. Continue until next is null.
curl "${RTD_HOST}/api/v3/search/?q=authentication"
curl "${RTD_HOST}/api/v3/search/?q=project:docs%20authentication"
# Sphinx
curl "${RTD_HOST}/api/v3/search/?q=project:sphinx%20configuration"
curl "${RTD_HOST}/api/v3/search/?q=project:sphinx%20autodoc"
# Requests
curl "${RTD_HOST}/api/v3/search/?q=project:requests%20proxies"
curl "${RTD_HOST}/api/v3/search/?q=project:requests%20authentication"
# Read the Docs
curl "${RTD_HOST}/api/v3/search/?q=project:readthedocs%20build"
curl "${RTD_HOST}/api/v3/search/?q=project:readthedocs%20redirects"
curl "${RTD_HOST}/api/v3/search/?q=API&page=2"
import os
import requests
response = requests.get(
f"{os.environ['RTD_HOST']}/api/v3/search/",
params={"q": "REST API"}
)
data = response.json()
for result in data['results']:
print(f"{result['project']}: {result['title']}")
print(f" Domain: {result['domain']}")
print(f" Path: {result['path']}")
def search_all(query):
all_results = []
page = 1
while True:
response = requests.get(
f"{os.environ['RTD_HOST']}/api/v3/search/",
params={"q": query, "page": page}
)
data = response.json()
all_results.extend(data['results'])
if not data['next']:
break
page += 1
return all_results
No authentication required: The Search API is public and does not require API keys or authentication.
Rate limiting: The API applies reasonable rate limits. If you receive HTTP 429, implement exponential backoff.
Private documentation excluded: Only publicly available documentation is searchable. Private projects are not included.
Search delay: The search index updates with a slight delay. New documentation may not appear immediately.
Empty results: If a query returns no results, try simpler keywords or browse the project directly on Read the Docs.
Project scoping recommended: The global index is large and queries can be broad. For most use cases, include a project:{project-slug} filter in q to scope results to the relevant documentation project.
Triage Read the Docs build failures using build logs and config context. Use when a build fails, logs need analysis, or you need fix recommendations.
Optimize Read the Docs build performance and resource usage. Use when Read the Docs builds are slow, timing out, or hitting memory limits, or when users want to speed up builds by adjusting formats, dependencies, conda/mamba usage, or Python API documentation strategy.
Manage Read the Docs projects via the RTD API. Use when creating projects, listing repos, triggering builds, syncing versions, or checking build status on Read the Docs.
Manage Read the Docs redirects via the RTD API. Use when listing, creating, updating, or deleting custom redirects for a project.
Create or update Read the Docs `.readthedocs.yaml` v2 configuration files for Sphinx or MkDocs builds, including build images/tools, dependency installs, formats, custom build jobs/commands, conda environments, submodules, and search settings. Use when a user asks for a Read the Docs config file, YAML changes, or build behavior updates.
Full Read the Docs API v3 client guidance. Use when building or updating an API client, generating requests, or answering questions about Read the Docs API v3 endpoints (projects, versions, builds, subprojects, translations, redirects, environment variables, organizations, remote VCS resources, or embed content).