Notion API: what you can do and how to use it with AI agents
The Notion API lets you read and write pages, blocks and databases, search content and comment. Teams that keep a wiki, projects and processes in Notion use it to automate them. Access is open, through an internal integration with a token or a public integration with OAuth, and it reaches only pages shared with the integration.
What the Notion API offers
Pages
Create and update pages and their properties.
Blocks
Read and write content: paragraphs, lists, tables, headings and other blocks.
Databases
Query with filters and sorting, create items and change properties.
Search
Find pages and databases the integration can access.
Comments
Read and create comments on pages and discussions.
Users
List of workspace members, used to assign owners.
How to access the Notion API
- Public APIAn internal integration with a secret token generated in Notion, or a public integration with OAuth 2.0. In both cases, pages must be shared with the integration.
- The API limits requests per second: large imports should be spaced out.
- The integration sees only what is shared with it: review sharing for sensitive areas.
- Some block types have limited API support: test the format before you automate.
Official documentation: developers.notion.com
What an iTeam agent does with the Notion API
Meeting notes in the project database
After the meeting, the agent creates the notes page in the right project, lists decisions and creates the tasks in the database with an owner and a due date.
A wiki that answers in Slack
The agent finds the relevant page in the Notion wiki and answers the question with the link, instead of someone searching by hand.
Outdated page
The agent finds process pages with no edits in months and asks the owner whether they are still valid, logging the review.
Pipeline in a database
Leads or purchase requests kept in a Notion database are updated by the agent as e-mail replies arrive.
From the credential to the agent at work, with approval
Create the integration in Notion
An administrator creates the integration with minimum capabilities (read, insert, update content) and shares only the pages needed.
Register the token in the iTeam vault
The token stays in the vault and each agent gets access to the areas it needs, such as the wiki for the internal support agent.
Test with approval
Creating pages can run directly. Edits to official pages and deletions start with human approval.
Ready-made AI teams that use Notion
Questions about the Notion API
Is the Notion API free?
Generally yes: the API is available on Notion plans with no per-call charge, within usage limits.
Do I need to code to use the Notion API with iTeam?
Not necessarily. Notion has a connector in the app catalog, and the deployment team sets up the flows with you.
Does the agent see all of my Notion?
No. It accesses only the pages and databases explicitly shared with the integration.
