Notion API
Search, query data sources, create and update pages, edit blocks, comment and upload files with Notion-Version 2026-03-11.
Productivity & workspaceGuided#notion#productivity#databases#pages#blocks#workspace
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The Notion API lets your code read and write a Notion workspace: search pages, query databases, create and update pages and their properties, add and edit page content (blocks), comment, and upload files. It is a JSON REST API at https://api.notion.com/v1. This collection uses Notion-Version 2026-03-11, the latest version on 17 November 2026, which includes the data source model introduced in 2025-09-03.
Create a connection and get a token
- As a workspace owner, open the Developer portal and create a new internal connection (integration) for your workspace.
- Choose its capabilities: read, update and insert content; read and insert comments (off by default); and user information if you need it.
- Open the connection's Configuration tab and copy the API token into notionToken (secret). A personal access token, which acts as you, also works.
- Share content with it. A connection sees nothing until you share pages with it: open a page or database in Notion, click ••• (top right) > Add connections, and choose your connection. Most
404 object_not_founderrors mean this step was missed.
Public integrations used by other workspaces use OAuth 2.0 instead (https://api.notion.com/v1/oauth/authorize and /v1/oauth/token). See Authorization.
Authentication and headers
Every request needs Authorization: Bearer <token> and Notion-Version: 2026-03-11; requests with a body also send Content-Type: application/json. Without the version header you get 400 missing_version. Pinning the version keeps responses stable; read the versioning page and upgrade guides before changing it.
Databases, data sources and pages
A database is now a container that can hold several data sources. Each data source has its own property schema and rows, and each row is a page. Get the data source ID from a database (data_sources array) or from Search, then query it, read its schema and create pages with parent.data_source_id. Version 2026-03-11 also renamed archived to in_trash and replaced after with position when appending blocks.
How to use this collection
Run 1. Start here, then 2. Databases and data sources, 3. Pages and properties, 4. Blocks, 5. Comments and 6. File uploads. Each create request saves its ID for the next ones. Change the example property names (Name, Status, Priority, Due) to your own schema.
Common errors
| HTTP | code | What to do |
|---|---|---|
| 400 | validation_error | Read message: usually a property name, type or option that does not match the schema, or a limit was exceeded. |
| 400 | missing_version | Add the Notion-Version header. |
| 401 | unauthorized | Wrong or revoked token. |
| 403 | restricted_resource | The connection lacks a capability (for example comments) or permission. |
| 404 | object_not_found | The ID is wrong or the page/database is not shared with the connection. |
| 409 | conflict_error | Concurrent edit; retry. |
| 429 | rate_limited | Wait the Retry-After seconds, then retry. |
| 5xx / 529 | service_unavailable, service_overload | Temporary; retry with backoff. |
Limits and pricing
Requests are rate limited per connection (an average of a few per second, higher on Business and Enterprise) and per workspace, and payloads have size limits (for example 100 blocks per array and 2,000 characters per rich text item). See Request limits, status codes and the API reference.
Endpoints 19
1. Start here
- GETRetrieve your bot user
/users/meReturns the bot user behind your token: type: bot, its name, and a bot object with owner (the workspace for internal connections, or a user for personal… - POSTSearch pages and data sources
/searchSearches the titles of everything shared with the integration. An empty result list almost always means nothing has been shared yet: open a page in Notion,… - GETList users
/usersLists the people and bots in the workspace (guests are not included). Needs the Read user information capability; person users include person.email when the…
2. Databases and data sources
- GETRetrieve a database (find its data sources)
/databases/{{databaseId}}Returns the database container: title, parent, is_inline, in_trash, url and the data_sources array (id + name of each source). The first source's ID is saved… - GETRetrieve a data source (schema)
/data_sources/{{dataSourceId}}Returns the data source's properties schema: each property's id, name, type (title, rich_text, number, select, multi_select, status, date, people, checkbox,… - POSTQuery a data source
/data_sources/{{dataSourceId}}/queryReturns the pages (rows) of a data source, filtered and sorted. Add the query parameter filter_properties to return only some properties. One query stops at…
3. Pages and properties
- POSTCreate a page in a data source
/pagesAdds a row to a data source. parent is {"type": "data_source_id", "data_source_id": ...} (use page_id to create a sub-page under a normal page; then only… - GETRetrieve a page
/pages/{{newPageId}}Returns a page's metadata and property values (not its content: read that with Retrieve block children). Each property has an id; the test saves the title… - PATCHUpdate page properties
/pages/{{newPageId}}Changes property values of a page. Send only the properties to change; the rest keep their values. Arrays (multi-select, people, relation) replace the whole… - GETRetrieve a page property item
/pages/{{newPageId}}/properties/{{propertyId}}Reads one property of a page by its ID (propertyId, saved by Retrieve a page; the property name also works). Simple types (select, status, number, date...)…
4. Blocks (page content)
- PATCHAppend block children
/blocks/{{newPageId}}/childrenAdds blocks to a page or to a block that can hold children. children is an array (at most 100 per request, nested up to two levels). Each block has type and a… - GETRetrieve block children
/blocks/{{newPageId}}/childrenReads the content of a page (or the children of a block), one level at a time. Blocks with has_children: true need their own call to read what is inside them,… - PATCHUpdate a block
/blocks/{{blockId}}Changes one block's content. Send the key of the block's type with the new values, for example {"to_do": {"checked": true}}; fields you send replace their old… - DELETEDelete a block
/blocks/{{blockId}}Moves a block (or a page, by its ID) to the trash: the response shows in_trash: true. It can be restored by updating the block or page with in_trash: false.…
5. Comments
- POSTCreate a comment on a page
/commentsStarts a comment on a page (parent.page_id) or block (parent.block_id), or replies in an existing thread with discussion_id instead of parent. Give the text… - GETList comments
/commentsLists the open (unresolved) comments on a page or block: pass its ID as block_id. Results include discussion_id, so you can group them into threads and reply.…
6. File uploads
- POST1) Create a file upload
/file_uploadsStarts an upload and returns a File Upload object with id (saved into fileUploadId), status: pending, upload_url and expiry_time. Default mode single_part is… - POST2) Send the file contents
/file_uploads/{{fileUploadId}}/sendSends the file bytes to the upload created in step 1, as multipart/form-data with the file in the file field (choose it in the body tab; do not set the… - PATCH3) Attach the upload as an image block
/blocks/{{newPageId}}/childrenUses the uploaded file in an image block appended to the page. The block points to the upload with {"type": "file_upload", "file_upload": {"id": ...}}; use a…
API details
- Base URL
https://api.notion.com/v1- Authentication
- A bearer token in the Authorization header
- Operations
- 19 operations on 19 pathsGET 8POST 6PATCH 4DELETE 1
- Main resources
- 1. Start here 32. Databases and data sources 33. Pages and properties 44. Blocks (page content) 45. Comments 26. File uploads 3
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-17 - Links
- Documentation
How to test the Notion API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Notion API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Retrieve your bot user” (GET /users/me), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Notion API?
Search, query data sources, create and update pages, edit blocks, comment and upload files with Notion-Version 2026-03-11. It is listed under Productivity & workspace and has 19 endpoints.
Who publishes the Notion API?
It is listed from Notion's public API description (an OpenAPI document), not published by Notion on Swastik Codes. Anyone who controls notion.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Notion API?
Requests go to https://api.notion.com/v1. Endpoint paths are added to this base URL.
How do I authenticate with the Notion API?
With A bearer token in the Authorization header.
How many endpoints does the Notion API have?
19 operations on 19 paths (8 GET, 6 POST, 4 PATCH, 1 DELETE). The largest groups are 1. Start here, 2. Databases and data sources, 3. Pages and properties, 4. Blocks (page content).
Is forking the Notion API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.