majiayu000 Read the Docs Search API
Query the public Read the Docs Search API to find documentation across millions of pages.
Step-by-step instructions
1. Make a search request
Query the API using:
GET https://readthedocs.org/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.
2. Parse the response
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"
}
]
}
]
}
3. Handle pagination
If there are more results, use the next URL to fetch the next page. Continue until next is null.
Examples
Search for authentication documentation
curl "https://readthedocs.org/api/v3/search/?q=authentication"
Search within a specific project
curl "https://readthedocs.org/api/v3/search/?q=project:docs%20authentication"
Project-scoped quick queries
# Sphinx
curl "https://readthedocs.org/api/v3/search/?q=project:sphinx%20configuration"
curl "https://readthedocs.org/api/v3/search/?q=project:sphinx%20autodoc"
# Requests
curl "https://readthedocs.org/api/v3/search/?q=project:requests%20proxies"
curl "https://readthedocs.org/api/v3/search/?q=project:requests%20authentication"
# Read the Docs
curl "https://readthedocs.org/api/v3/search/?q=project:readthedocs%20build"
curl "https://readthedocs.org/api/v3/search/?q=project:readthedocs%20redirects"
Search with pagination
curl "https://readthedocs.org/api/v3/search/?q=API&page=2"
Parse results with Python
import requests
response = requests.get(
"https://readthedocs.org/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']}")
Get all paginated results
def search_all(query):
all_results = []
page = 1
while True:
response = requests.get(
"https://readthedocs.org/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
Common edge cases
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.