Notion

Notion logo
Workspace for documents, wikis, databases and project management with flexible customisation for teams.

Notion API

Sign in
Bearer token. Authenticate with a personal access token (PAT) or internal connection API token by including it in the Authorization header as a Bearer token.Source
Base address
https://api.notion.comrestSource
Rate limits
Per-connection rate limits based on workspace plan: Business and Enterprise plans allow 600 requests per minute (10 per second average); all other plans allow 180 requests per minute (3 per second average). A separate per-workspace limit is shared across all connections.Source
Paging
Cursor paging: send start_cursor, page size page_size; the answer's next_cursor holds the next position.Source
Webhooks
commentCreatedcommentDeletedcommentUpdateddataSourceContentUpdateddataSourceCreateddataSourceDeleteddataSourceMoveddataSourceSchemaUpdateddataSourceUndeleteddatabaseContentUpdateddatabaseCreateddatabaseDeleteddatabaseMoveddatabaseSchemaUpdateddatabaseUndeletedfileUploadCompletedfileUploadCreatedfileUploadExpiredfileUploadUploadFailedpageContentUpdatedpageCreatedpageDeletedpageLockedpageMovedpagePropertiesUpdatedpageTranscriptionBlockTranscriptDeletedpageUndeletedpageUnlockedviewCreatedviewDeletedviewUpdatedEvery webhook request from Notion includes an X-Notion-Signature header, which contains an HMAC-SHA256 hash of the request body, signed with your verification_token.Source
Notion API endpoints
TypeEndpointReturns
GET/v1/users/meRetrieve your token's bot user
GET/v1/users/{user_id}Retrieve a user
GET/v1/usersList all users
GET/v1/pages/{page_id}Retrieve a page
GET/v1/pages/{page_id}/properties/{property_id}Retrieve a page property item
GET/v1/pages/{page_id}/markdownRetrieve a page as markdown
GET/v1/async_tasks/{task_id}Retrieve an async task
GET/v1/blocks/{block_id}Retrieve a block
GET/v1/blocks/{block_id}/childrenRetrieve block children
GET/v1/data_sources/{data_source_id}Retrieve a data source
GET/v1/data_sources/{data_source_id}/templatesList templates in a data source
GET/v1/databases/{database_id}Retrieve a database
GET/v1/commentsList comments
GET/v1/comments/{comment_id}Retrieve a comment
GET/v1/file_uploadsList file uploads
GET/v1/file_uploads/{file_upload_id}Retrieve a file upload
GET/v1/custom_emojisList custom emojis
GET/v1/viewsList views
GET/v1/views/{view_id}Retrieve a view
GET/v1/views/{view_id}/queries/{query_id}Get view query results
GET/v1/agents/{agent_id}Get agent
GET/v1/agents/{agent_id}/insightsGet agent insights
GET/v1/ai/pluginsList skills plugins
GET/v1/ai/plugins/{id}Get a plugin directory
GET/v1/ai/skills/{id}Get a skill directory
GET/v1/sessions/{session_id}Retrieve a session
POST/v1/pagesCreate a page
PATCH/v1/pages/{page_id}Update page
POST/v1/pages/{page_id}/moveMove a page
PATCH/v1/pages/{page_id}/markdownUpdate a page's content as markdown
PATCH/v1/blocks/{block_id}Update a block
DELETE/v1/blocks/{block_id}Delete a block
PATCH/v1/blocks/{block_id}/childrenAppend block children
PATCH/v1/data_sources/{data_source_id}Update a data source
POST/v1/data_sources/{data_source_id}/queryQuery a data source
POST/v1/data_sourcesCreate a data source
PATCH/v1/databases/{database_id}Update a database
POST/v1/databasesCreate a database
POST/v1/searchSearch by title
POST/v1/commentsCreate a comment
PATCH/v1/comments/{comment_id}Update a comment
DELETE/v1/comments/{comment_id}Delete a comment
POST/v1/file_uploadsCreate a file upload
POST/v1/file_uploads/{file_upload_id}/sendUpload a file
POST/v1/file_uploads/{file_upload_id}/completeComplete a multi-part file upload
POST/v1/viewsCreate a view
PATCH/v1/views/{view_id}Update a view
DELETE/v1/views/{view_id}Delete a view
POST/v1/views/{view_id}/queriesCreate a view query
DELETE/v1/views/{view_id}/queries/{query_id}Delete a view query
POST/v1/blocks/meeting_notesCreate a meeting note
POST/v1/blocks/meeting_notes/queryQuery meeting notes
POST/v1/agents/queryQuery agents
DELETE/v1/agents/{agent_id}Delete agent
PATCH/v1/agents/{agent_id}/statusUpdate agent status
PATCH/v1/agents/{agent_id}/credit_limitUpdate agent credit limit
POST/v1/agents/batchApply many agent operations
POST/v1/sessionsUpdate a session
POST/v1/sessions/queryQuery sessions
POST/v1/sessions/{session_id}/events/queryQuery session events
POST/v1/sessions/{session_id}/cancelCancel a session
POST/v1/oauth/tokenExchange an authorization code for an access and refresh token
POST/v1/oauth/revokeRevoke a token
POST/v1/oauth/introspectIntrospect a token

Working with it through the API

How well Notion works through its API for an assistant
QuestionRatingWhy
Can an assistant read everything?good15 list endpoints (15 with paging) among 26 read operations and 64 in all.Source
Does it tell us when something changes?goodWebhooks exist (31 events), signed.Source
Is there an official library?goodOfficial JavaScript (@notionhq/client), TypeScript (@notionhq/workers).Source
Is there an MCP server?goodThe vendor runs an MCP server at https://mcp.notion.com/mcp.Source
How easy is it to sign in?goodA static credential the owner makes in the tool: no consent screen.Source

MCP server

Address
https://mcp.notion.com/mcpSource
What it is
Official Notion MCP server

Checked on 2026-10-07 in the developer documentation.

How to use Notion

If you've decided to use Notion for your B2B marketing needs, here's a step-by-step guide on how to set up and get the most out of the tool.

Read the full guide

Setting up your Notion workspace

  1. Create a workspace: First, sign up for Notion and create your workspace. Once you're in, you can start by building a dashboard that includes links to all the important areas of your work, such as campaigns, content, tasks, and knowledge management. You can start with a template, or create one from scratch.
  2. Set up pages for different projects: In Notion, everything is organised into pages. Create pages for each of your major projects, such as a marketing campaign, content strategy, or client management. Within each page, you can add subpages, tasks, and other details relevant to that project. This keeps everything organised and easy to access.
  3. Create databases: Databases in Notion are powerful. You can use them to track tasks, manage content calendars, or even store customer information. Create a database for each part of your process for example, a "Campaign Tracker" database to track the progress of each campaign, including start dates, deadlines, and status updates. You can use different views such as a table, board (Kanban), or calendar depending on how you want to visualise your data.
  4. Build your task management system: Notion allows you to create detailed task lists, including assignees, due dates, and priority levels. You can set up tasks for each team member, link them to specific campaigns, and track their progress. Using tags or categories makes it easy to filter tasks based on priority or completion status.
  5. Collaborate with your team: Notion excels at collaboration. You can invite team members to your workspace, assign tasks, and share documents in real-time. If you're working on a marketing campaign, for example, you can all contribute ideas, track progress, and leave comments within the same page.
  6. Use templates for efficiency: Notion has a library of templates to help you get started quickly. You can use templates for meeting notes, project management, content planning, and more. Customise these templates to suit your needs and save time on setting up your workspace.

Managing your content calendar

  1. Create a content calendar: For B2B marketers, keeping track of content is crucial. In Notion, you can create a content calendar using a database view with dates and categories for each piece of content. This will help you plan blog posts, social media content, webinars, and more in a clear and organised way.
  2. Add task details: Each content item in the calendar can be linked to a task list where team members can track progress and deadlines. You can also link content ideas, assign tasks, and track the content creation process in one place.

Monitoring team progress and performance

  1. Set up dashboards: Notion lets you create custom dashboards where you can bring together various pages and databases. Create a dashboard to track overall marketing performance, project timelines, and team progress. Link it to your task management system, content calendar, and campaign tracker for an at-a-glance view of your team's work.
  2. Review analytics: While Notion itself isn't built for advanced analytics, it's an excellent place to store and review project data. You can integrate Notion with other tools, such as Google Analytics or your CRM, to pull in relevant data and store it in your workspace.

Conclusion

Notion is an incredibly powerful tool for B2B marketers looking to centralise project and task management. Its flexibility, customisation options, and collaborative features make it ideal for managing everything from marketing campaigns to content creation. While it's great for smaller teams, larger operations may face some limitations as the need for automation and advanced reporting increases. However, if you're looking for an all-in-one workspace that's highly adaptable to your workflow, Notion is my go-to tool for managing everything in one place.

How to automate Notion

Native integrations

Notion connects to the apps around it, such as Slack, GitHub and Google Drive, and the Business plan adds premium connections. A useful first step is to connect Slack so that a thread can become a task in a database without copy and paste.

API and webhooks

Notion has a public REST API with documentation for databases, pages and content. Use it to create database rows from your own systems. A form submission or a new HubSpot deal could become a task row in the delivery database.

MCP server

Notion runs an official hosted MCP server that uses OAuth. A client such as Claude, Cursor or Codex can search, read, create and update pages and databases that you have access to. Workspace owners control which clients may connect from the Connections settings. A good use is asking an agent for a weekly summary of what changed in a project database.

Built-in automation

Notion AI agents can take on repeat work inside the workspace, for example triaging feedback or compiling a weekly report. These are on the Business plan and above, and usage beyond the trial is metered.