Notion

1. Overview

Notion is an all-in-one workspace that provides components such as notes, databases, kanban boards, wikis, calendars, and reminders. The Notion API allows for programmatic integration with its powerful organizational tools.

Through GoInsight's Notion node, you can seamlessly integrate your workspace management into automated workflows. This enables you to perform a full range of operations on your Notion pages, databases, comments, and users, including:

• Page Management: Create, retrieve, update, search, and archive pages within databases or other pages.
• Database Interaction: List all available databases, retrieve specific database schemas, and query pages within them using advanced filters and sorting.
• Content and Comments: Append new content blocks to pages, retrieve lists of child blocks, and fetch comments for a specific block.
• User Management: Fetch lists of users in the workspace or retrieve individual user details.

2. Prerequisites

Before using this node, you need to have a valid Notion account. You may also need appropriate permissions within your Notion workspace to create an integration and share pages or databases with it.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This node provides operations centered around the core resources in Notion: Databases, Pages, Blocks, Comments, and Users. The table below summarizes the available actions.

Operation Details

Get a Database

Retrieves a database object from Notion by its ID.

Input Parameters:

• DatabaseId: The ID of the database to retrieve.

Output:

• Database (object): The Notion database object returned by the API, including its schema and Metadata.
• StatusCode (number): Operation status code: 200 indicates success, -1 indicates parameter validation error, 500 indicates exception, other values correspond to HTTP status codes returned by the API.
• ErrorMessage (string): Error message if the operation failed; empty if successful.

Get Many Databases

Retrieves a list of databases shared with the integration in the Notion workspace, supporting pagination with cursor and page size.

Optional Parameters:

• StartCursor: The cursor from which to start retrieving. Defaults to empty.
• PageSize: The number of results per page (1-100). Defaults to API default if not specified.

Output:

• Results (object-array): A list of database objects retrieved.
• HasMore (bool): Indicates if more results are available.
• NextCursor (string): Cursor for the next page, empty if none.
• StatusCode (number): Operation result code; -1 for parameter error, 500 for exceptions, other HTTP status codes for failures.
• ErrorMessage (string): Error message if any; empty string if successful.

Search a Database

Searches Notion databases using the /v1/search endpoint, filtering results by object type "database".

Optional Parameters:

• Query: Search keyword.
• FilterObject: Filter by object type, must be "database". Default is "database".
• PageSize: Maximum number of items per page. Default is API default.
• StartCursor: Pagination cursor from previous response.

Output:

• Results (object-array): List of database objects matching the search criteria.
• NextCursor (string): Cursor for fetching the next page of results.
• HasMore (bool): Indicates if there are more results.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Create a Database Page

Creates a new page in a Notion database using the /v1/pages endpoint.

Input Parameters:

• DatabaseId: The ID of the target database.
• PropertiesJson: JSON string representing the page properties matching Notion API's properties schema.

Optional Parameters:

• ChildrenJson: JSON string representing block children for page content.

Output:

• PageId (string): The ID of the newly created page.
• CreatedPage (object): The full page object returned by Notion API.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Create a Page

Creates a new page in Notion using the /v1/pages endpoint. Supports specifying parent type as database or page.

Input Parameters:

• ParentType: The type of parent, either "database_id" or "page_id".
• ParentId: The ID of the parent database or page.
• PropertiesJson: JSON string representing the page properties matching Notion API's properties schema.

Optional Parameters:

• ChildrenJson: JSON string representing block children for page content.

Output:

• PageId (string): The ID of the newly created page.
• CreatedPage (object): The full page object returned by Notion API.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Get a Database Page

Retrieves a page from a Notion database by page ID using the /v1/pages/{page_id} endpoint.

Input Parameters:

• PageId: The ID of the page to retrieve.

Output:

• Page (object): The page object returned by Notion API.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Get Many Database Pages

Retrieves multiple pages from a Notion database using the /v1/databases/{database_id}/query endpoint.

Input Parameters:

• DatabaseId: The ID of the target database.

Optional Parameters:

• FilterJson: JSON string representing filter object as per Notion API.
• SortsJson: JSON string representing sorts array as per Notion API.
• PageSize: Maximum number of items per page. Default is API default.
• StartCursor: Pagination cursor from previous response.

Output:

• Results (object-array): List of page objects matching the query.
• NextCursor (string): Cursor for fetching next page.
• HasMore (bool): Indicates if there are more results.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Update a Database Page

Updates properties of a database page in Notion using the /v1/pages/{page_id} endpoint.

Input Parameters:

• PageId: The ID of the page to update.
• PropertiesJson: JSON string representing the properties to update as per Notion API.

Output:

• UpdatedPage (object): The full page object returned by Notion API after update.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Search a Page

Searches for pages in a Notion workspace using the /v1/search endpoint.

Optional Parameters:

• Query: The search query string.
• FilterJson: JSON string representing the filter object as per Notion API.
• SortJson: JSON string representing the sort object as per Notion API.
• PageSize: Maximum number of items per page. Default is API default.
• StartCursor: Pagination cursor from previous response for fetching next page.

Output:

• Results (object-array): List of page objects matching the search criteria.
• NextCursor (string): Cursor for fetching the next page of results.
• HasMore (bool): Indicates if there are more results available.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Archive Page

Archives a Notion page by setting its archived status to true using the /v1/pages/{page_id} endpoint.

Input Parameters:

• PageId: The ID of the page to archive.

Output:

• ArchivedPage (object): The page object returned by Notion API including its archived status.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Append a Block

Appends new child blocks to a specified Notion block. This endpoint adds blocks as children under the given parent block.

Input Parameters:

• BlockId: The ID of the parent block to which to append children.
• Children: A list of block objects conforming to Notion API specification.

Optional Parameters:

• AfterBlockId: The ID of the existing child block after which new blocks should be inserted. Defaults to append at the end.

Output:

• Children (object-array): The list of newly appended child block objects.
• StatusCode (number): Operation status code: 200 indicates success, -1 indicates parameter validation error, other values correspond to HTTP status codes returned by the API.
• ErrorMessage (string): Error message if the operation failed; empty if successful.

Get Many Child Blocks

Retrieves the list of child blocks under a specified Notion block, supporting pagination with cursor and page size.

Input Parameters:

• BlockId: The ID of the parent block whose children are to be retrieved.

Optional Parameters:

• StartCursor: The cursor for pagination, from which to start retrieving. Defaults to empty.
• PageSize: The number of results per page (1-100). Defaults to API default if not specified.

Output:

• Children (object-array): A list of child block objects retrieved.
• NextCursor (string): The cursor to fetch the next page of results; empty if none.
• HasMore (bool): Indicates whether there are more results to retrieve.
• StatusCode (number): Operation status code: 200 for success, -1 for parameter errors, 500 for exceptions, other codes as returned.
• ErrorMessage (string): Error message if the operation failed; empty if successful.

Get Many Comments

Retrieves the list of comments for a specified Notion block and supports pagination parameters start_cursor and page_size.

Input Parameters:

• BlockId: The ID of the Notion block to retrieve comments from.

Optional Parameters:

• StartCursor: The cursor to start pagination from.
• PageSize: The maximum number of comments to return per page.

Output:

• Comments (object-array): A list of comment objects as returned by Notion API.
• HasMore (bool): Indicates if there are more comments available.
• NextCursor (string): The cursor to use for the next page of results, empty if none.
• StatusCode (number): HTTP status code of the operation: 2xx success, -1 parameter error, 500 exception.
• ErrorMessage (string): Error description if any.

Get a User

Retrieves a user object from Notion using the /v1/users/{user_id} endpoint.

Input Parameters:

• UserId: The ID of the user to retrieve.

Output:

• User (object): The user object returned by the Notion API.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

Get Many Users

Retrieves a list of users from Notion using the /v1/users endpoint.

Optional Parameters:

• PageSize: Maximum number of users per page, up to 1000. Default is API default.
• StartCursor: Pagination cursor from previous response for fetching next page.

Output:

• Users (object-array): List of user objects returned by Notion API.
• NextCursor (string): Cursor for fetching the next page of results.
• HasMore (bool): Indicates if there are more results available.
• StatusCode (number): HTTP status code of the request; -1 indicates parameter validation error; 500 indicates exception.
• ErrorMessage (string): Error message if any.

5. Example Usage

This section will guide you through creating a simple workflow to add a new page to a Notion database.

The workflow will consist of: Start -> Create a Database Page -> Answer.

Step-by-Step Guide

1. Add the Tool Node
   • In the workflow canvas, click the "+" button to add a new node.
   • Select the "Tools" tab in the pop-up panel.
   • Find and select "Notion" from the list of tools.
   • In the list of supported operations for Notion, click on "Create a Database Page" to add the node to the canvas.
2. Configure the Node
   • Click on the newly added "Create a Database Page" node to open its configuration panel on the right.
   • Credentials: In the credentials field at the top, select your pre-configured Notion credential from the dropdown menu.
   • Parameters: Fill in the required input parameters for the action.
   • DatabaseId: Enter the ID of the Notion database where you want to create the new page. You can find this ID in the URL of your Notion database.
   • PropertiesJson: Provide a JSON string that defines the properties of the new page. For example, to set a "Name" property for a page, you would enter: {"Name": {"title": [{"text": {"content": "New Task from GoInsight"}}]}}. The structure must match the Notion API's requirements for page properties.
3. Run and Verify
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
   • Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful run, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the operation was successful.

After completing these steps, your workflow is fully configured. When you run it, a new page will be created in your specified Notion database.

6. FAQs

Q: I'm getting a 401 Unauthorized error. What should I do?

A: This error typically indicates an issue with your credentials or permissions. Please check the following:

• Correct Token: Ensure the integration token you provided in the credentials is correct and has not expired.
• Shared Database/Page: Make sure you have explicitly shared the target database or page with your Notion integration. Go to the page/database in Notion, click "Share", and invite your integration.

Q: My PropertiesJson or ChildrenJson is causing an error. How can I fix it?

A: The JSON provided must be valid and strictly adhere to the Notion API's schema.

• Validate your JSON: Use an online JSON validator to ensure there are no syntax errors (e.g., missing commas, incorrect brackets).
• Check Notion API Docs: Refer to the official Notion API documentation for the correct structure for page properties and block objects. A common mistake is incorrect nesting or using the wrong property type.

7. Official Documentation

For more advanced use cases and detailed information about the Notion API, please refer to the Notion Developers Documentation.