.png)
Welcome to the Notion API reference. This is an early preview of the first features we plan to make available via private beta. We've got more in store, but we're aiming to gather feedback and improve upon the subset presented here so that we have a solid platform to build the rest atop.
The Notion API gives you access to the same pages and databases you can create in the Notion app via an interface that you can expect to remain stable.
The interface follows RESTful conventions when possible, with most operations performed via GET, POST, PATCH, and DELETE requests on page and database resources. Request and response bodies are encoded as application/json.
You'll need to authenticate each request with an API key using HTTP basic authentication. To create an API key, you must first create a bot. You can think of bots as equivalent to guest users in your workspace: when you create a bot in your workspace, they have access to any databases, pages, or subpages that you explicitly share with them via the Share menu.
Learn more about creating bots and making your first request in the Getting started guide.
Any operations that you perform through the API, like creating a new page, will be attributed to the bot.
Today's release, prepared and logged via page update by Doug EngelBot.
To see the API in action, we'll retrieve a user from the API using the Retrieve a user endpoint:
Request
curl <https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5> \\
-u sk_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns:
Response
{
"object": "user",
"id": "01da9b00-e400-4959-91ce-af55307647e5",
"type": "person",
"name": "Avocado Lovelace",
"email": "avo@example.org",
"avatar_url": "<https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg>",
"groups": [
{
"object": "group",
"id": "ef7f4c7e-8ce3-4add-9fc1-a34e078eb9c0",
"name": "Product"
}
]
}
Learn about the steps needed to make your first API request in the Getting started guide.
Familiarize yourself with Notion's data model before diving into the endpoints.
This documentation covers a small subset of what we want the API to become. Check out what we're thinking of building next.
Databases help you structure information in Notion in a variety of ways. They let you organize, categorize, label, filter, search, and view information to get jobs done.