Notion APIdevelopers.notion.com ↗
Access Notion's developer documentation via API. Search, list all pages, and retrieve full markdown content for any doc page across the Notion API reference.
What is the Notion API?
This API provides structured access to the Notion developer documentation across 3 endpoints, letting you list the full documentation index, retrieve any single page as markdown, and run full-text searches across all content. The search_docs endpoint returns ranked results with relevance scores, breadcrumbs, and OpenAPI operation strings for endpoint reference pages, making it straightforward to build documentation tooling or AI assistants grounded in current Notion API content.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/0f772cb3-4e0c-441c-b344-ed13c766f6c5/list_pages' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace developers-notion-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: NotionDocs SDK - access Notion API documentation programmatically."""
from parse_apis.developers_notion_com_api import NotionDocs, PageNotFound
client = NotionDocs()
# List all available documentation pages
for page in client.pages.list(limit=5):
print(page.title, "-", page.description)
# Search for specific documentation topics
result = client.pages.search(query="database query", limit=1).first()
if result:
print(result.title, result.section, f"(score: {result.score})")
print("Breadcrumbs:", result.breadcrumbs)
# Navigate from search result to full page content
full = result.full_page()
print(full.title, "-", full.content[:200])
# Fetch a page directly by path
try:
page = client.pages.get(path="reference/retrieve-a-page")
print(page.title, "-", page.path)
except PageNotFound as exc:
print(f"Page not found: {exc.path}")
print("exercised: pages.list / pages.search / full_page / pages.get")
Retrieves the full documentation index with every page in the Notion developer docs including title, path, URL, and description. Results are returned as a single list; use get_page with a returned path to fetch full content.
No input parameters required.
{
"type": "object",
"fields": {
"pages": "array of page summaries",
"total": "integer"
},
"sample": {
"data": {
"pages": [
{
"url": "https://developers.notion.com/cli/get-started/authentication.md",
"path": "cli/get-started/authentication",
"title": "Authentication",
"description": "Log in to your Notion workspace and manage CLI credentials."
}
],
"total": 197
},
"status": "success"
}
}About the Notion API
What the API covers
The API exposes the entire Notion developer documentation site at developers.notion.com. list_pages returns a flat index of every documentation page — each entry includes a title, path, url, and description — along with a total count. This is the right starting point when you need to enumerate available content or build a navigation layer.
Fetching individual pages
get_page accepts a single required parameter, path, which maps directly to a page's location in the docs hierarchy (for example, reference/retrieve-a-page or guides/get-started). The response returns the page's title, its canonical path, and the full content field rendered as markdown. There is no leading slash in the path and no .md suffix — paths are as returned by list_pages or search_docs.
Searching the docs
search_docs takes a query string and returns ranked hits. Each result in the results array includes a title, path, section heading, a content preview snippet, breadcrumbs for context, a numeric relevance score, and — when the hit is an endpoint reference page — an openapi_operation string identifying the HTTP method and route. The total field and the echoed query field are also present at the top level. Use the path from any result with get_page to fetch the complete content.
The Notion API is a managed, monitored endpoint for developers.notion.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when developers.notion.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official developers.notion.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a documentation chatbot that retrieves up-to-date Notion API reference pages as markdown context using
get_page. - Index all Notion developer docs by calling
list_pagesand syncing titles and paths into an internal search tool. - Locate the correct API reference endpoint for a Notion object type using
search_docswith queries like 'database query'. - Generate a site map or navigation tree for an internal Notion API guide by consuming the full
list_pagesindex. - Validate that a documentation page still exists by checking whether a given
pathreturns content fromget_page. - Extract OpenAPI operation strings for all Notion endpoints by searching for endpoint terms and reading the
openapi_operationfield from results.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Notion have an official developer API?+
What does `search_docs` return beyond a text snippet?+
search_docs returns, per result: title, path, a section heading, a content preview, breadcrumbs (the location in the doc hierarchy), a numeric relevance score, and an openapi_operation string when the result corresponds to an API endpoint reference page. The total count and the original query are returned at the top level.Does `get_page` support fetching multiple pages or paginating through content?+
get_page fetches one page per call using the required path parameter and returns the full page content as a single markdown string — there is no pagination within a page. To retrieve multiple pages, call list_pages first to collect all paths, then issue individual get_page calls for each.