Notion

1. Overview

Notion is an all-in-one workspace that combines notes, docs, project management, and wikis. The Notion API allows you to programmatically interact with your workspace to automate workflows and manage data.

The Notion node in GoInsight enables you to integrate Notion capabilities directly into your automated processes. You can perform a wide range of actions, including:

• Page Management: Create, update, archive, and retrieve pages, whether they exist as standalone pages or items within a database.
• Database Operations: Query databases to filter and sort records, retrieve database metadata, and search for specific databases.
• Content Handling: Append content blocks to pages and retrieve child blocks to read page content.
• User & Comment Interaction: Retrieve user details and access comments associated with blocks or pages.

2. Prerequisites

Before using the Notion node, please ensure you have the following:

• A Notion Account: You need an active Notion account.
• An Internal Integration: You must create an internal integration in your Notion workspace settings (under "My connections" -> "Develop or manage integrations") to obtain an Internal Integration Token (Secret).
• Page Access: The integration must be explicitly added to the specific pages or databases you want to access. You can do this by opening the page in Notion, clicking the ... menu in the top right, selecting "Connections," and adding your integration.

3. Credentials

For detailed guidelines on how to acquire and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the following resources: Block, Comment, Database, Database Page, Page, and User.

Operation Details

Append a Block

Appends child blocks to an existing Notion block using the /v1/blocks/{block_id}/children endpoint. Risk Level: Medium. This action writes new content and has no dry-run mode; verify BlockId and Children before calling.

Input Parameters:

• BlockId: The unique identifier of the parent block. Can be a Page ID (appends to the end of the page) or any Block ID (appends to the child block list of that block). How to get Block ID: 1. Open the target page/block in Notion 2. Click the ... menu in the upper right corner → Copy link 3. The last segment of the URL is the ID (32-character string, e.g., abc123def456...) Can be obtained via Get a Block or Search action. Example: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
• Children: The list of child blocks to append. Each element is an object conforming to the Notion Block API specification. Common Block Type Examples: 1. Paragraph Text ``json { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{"type": "text", "text": {"content": "Hello World"}}] } } ` **2. To-Do Item** `json { "object": "block", "type": "to_do", "to_do": { "rich_text": [{"type": "text", "text": {"content": "Task description"}}], "checked": false } } ` **3. Heading** `json { "object": "block", "type": "heading_1", "heading_1": { "rich_text": [{"type": "text", "text": {"content": "Chapter 1"}}] } } `` Complete block type documentation: https://developers.notion.com/reference/block

Options:

• AfterBlockId: The ID of the existing child block after which new blocks should be inserted. If not provided, blocks will be appended to the end of the child list. Example: "abc123-def456-789ghi"

Output:

• Children (object-array): The list of newly appended child block objects. Each object contains core fields: - id (string): Block unique identifier - type (string): Block type (paragraph, heading_1, to_do, etc.) - created_time (string): Creation time (ISO 8601) - last_edited_time (string): Last edited time - has_children (boolean): Whether the block has children - archived (boolean): Whether the block is archived - {type} (object): Type-specific content object (e.g., paragraph.rich_text) Example: [{"id": "abc123", "type": "paragraph", "paragraph": {"rich_text": [...]}}]
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

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. This is a required parameter.

Options:

• StartCursor: The cursor for pagination, from which to start retrieving. Use NextCursor from previous response for next page. Leave empty for first page.
• PageSize: The number of results per page (1-100). Defaults to 50 if not specified.

Output:

• Children (object-array): Array of child block objects. Each block contains: id, type, created_time, last_edited_time, has_children, archived, and type-specific content (e.g., paragraph, heading, to_do, etc.).
• NextCursor (string): The cursor to fetch the next page of results. Use this as StartCursor for next request. Empty string if no more pages.
• HasMore (bool): Indicates whether there are more results to retrieve. True means you should make another request with NextCursor.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

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 unique identifier of the Notion block (page/database/block) to retrieve comments from. You can obtain BlockId by: - Method 1: Use 'Get Page Content' or 'Get Block Children' actions to get block list, extract the 'id' field from results - Method 2: Right-click a block in Notion web > Copy link, the 32-character string at the end is the BlockId (format with hyphens if needed) Example: "b55c9c91-384d-452b-81db-d1ef79372b75"

Options:

• StartCursor: Pagination cursor to start from. Leave empty for the first page query. For subsequent pages, use the 'NextCursor' value from the previous response. If 'HasMore' is false in the last response, no more queries are needed. Example (for next page): "7c6b1c95-de50-45ca-94e8-af65dd2e0c2c"
• PageSize: Maximum number of comments to return per page. Value range: 1-100 (Notion API limitation) Default: 100 (recommended to use maximum value to reduce API calls) If total comments exceed page_size, use the StartCursor parameter for pagination.

Output:

• Comments (object-array): Array of comment objects returned by Notion API. Each comment object contains the following core fields: - id (string): Unique comment identifier - parent (object): Parent object, includes 'type' and 'block_id' or 'page_id' - discussion_id (string): Discussion thread ID - created_time (string): Creation timestamp in ISO 8601 format - last_edited_time (string): Last edit timestamp - created_by (object): Creator information with 'id' and 'name' - rich_text (array): Comment content in rich text format Example: [{"id": "abc-123", "rich_text": [{"type": "text", "text": {"content": "Great work!"}}], "created_time": "2024-01-15T10:30:00.000Z"}]
• HasMore (bool): Boolean indicating whether more comments are available for pagination. If true, use 'NextCursor' to fetch the next page.
• NextCursor (string): Cursor string for fetching the next page of results. Empty string if no more pages available (HasMore=false).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get a Database

Retrieves a database object from Notion by its ID.

Input Parameters:

• DatabaseId: The unique identifier of the Notion database to retrieve. You can obtain the Database ID from the database URL in Notion (the 32-character string after the workspace name, with or without hyphens). Example: 668d797c-76e8-4ad2-98ad-e34d3a4aa84e

Output:

• Database (object): The Notion database object returned by the API. Key fields include: id (string, database UUID), title (array, database name), properties (object, schema definition with column names as keys), parent (object, parent container info), created_time (string, ISO 8601 timestamp), last_edited_time (string, ISO 8601 timestamp), archived (boolean, archive status), url (string, public URL). Each property in properties contains: id (column ID), name (column display name), type (column type such as title/text/number/select/multi_select/date/checkbox/url/email/phone_number/people/files/relation/rollup/formula), and type-specific configuration object.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Databases

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

Options:

• StartCursor: Pagination cursor for retrieving the next page of results. Leave empty for the first request, then use the 'NextCursor' value from the previous response. Format: UUID string (e.g., 'a1b2c3d4-e5f6-7890-abcd-ef1234567890').
• PageSize: The number of database results per page (range: 1-100). Defaults to 50. Note: Notion API's native default is 100. If the actual number of databases is less than the specified value, all available results will be returned with HasMore=false.

Output:

• Databases (object-array): A list of database objects retrieved from Notion. Each database object contains: 'id' (string, unique database identifier), 'object' (string, always 'database'), 'created_time' (ISO 8601 timestamp), 'last_edited_time' (ISO 8601 timestamp), 'title' (array, database title - extract plain text via title[0].text.content), 'properties' (object, schema of database properties), 'url' (string, direct link to the database), 'archived' (boolean), 'is_inline' (boolean), 'parent' (object, parent page/workspace info). Example: [{"id": "abc123", "title": [{"type": "text", "text": {"content": "Task Database"}}], "url": "https://notion.so/abc123"}]
• HasMore (bool): Indicates whether more results are available for pagination. If true, use the NextCursor value in the next request to retrieve the next page.
• NextCursor (string): Pagination cursor for retrieving the next page of results. Pass this value to the StartCursor parameter in the next request. Empty string if no more results are available (HasMore=false).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging. Default is 0 if the request did not reach the upstream API.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Search a Database

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

Options:

• Query: Search keyword for fuzzy matching against database titles. Notion performs case-insensitive partial matching. Leave empty to retrieve all databases. Example: "Project" will match "Project Tracker", "Marketing Projects".
• FilterObject: Filter by Notion object type. Must be "database" (default) to search for database objects. This is a technical parameter required by Notion API and typically does not need modification.
• PageSize: Maximum number of items per page (1-100). Default is 50 if not specified. Notion API enforces a hard limit of 100. Recommended value: 50 for balanced performance.
• StartCursor: Pagination cursor obtained from the 'NextCursor' field of a previous search response. Leave empty for the first request. Use the returned 'NextCursor' value to fetch subsequent pages. Example: "3d0e3e3e-1234-5678-90ab-cdef12345678"

Output:

• Results (object-array): List of database objects matching the search criteria. Each object contains: id (string): Database unique identifier, object (string): Always "database", created_time (string): ISO 8601 timestamp, last_edited_time (string): ISO 8601 timestamp, title (array): Database title (rich text format), url (string): Notion URL to the database, properties (object): Database schema definition.
• NextCursor (string): Cursor for fetching the next page of results. Use this value in the 'StartCursor' parameter of the next request. Empty string means no more pages.
• HasMore (bool): Indicates if there are more results available. True means you can fetch the next page using the NextCursor value.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Create a Database Page

Creates a new page in a Notion database using the /v1/pages endpoint. Risk Level: Medium. This action creates new Notion content and is NOT idempotent; retrying after a timeout may create duplicate database pages. Before retrying, search or query the database to confirm whether the page already exists.

Input Parameters:

• DatabaseId: The unique identifier of the target Notion database. How to obtain: Method 1: From Notion UI (Recommended for beginners) 1. Open Notion app or web 2. Navigate to the database you want to use: - Click the database in the sidebar, OR - Search for the database name (Cmd/Ctrl + P) 3. Click the "⋮⋮" menu (top-right) → "Copy link" 4. Paste the URL: https://notion.so/{workspace}/{database_id}?v=... 5. Extract the 32-character hexadecimal string between workspace name and ?v= - Example URL: https://notion.so/myworkspace/a1b2c3d4e5f6789012345678901234ab?v=123 - Extract: a1b2c3d4e5f6789012345678901234ab Method 2: From Action Output (For automation) - Use "Query a Database" action → extract id field from response - Use "Search" action with filter: {"property": "object", "value": "database"} → extract id field Format: 32-character hexadecimal (with or without hyphens) Example: a1b2c3d4e5f6789012345678901234ab or a1b2c3d4-e5f6-7890-1234-567890123456
• Properties: ⚠️ CRITICAL: Property names must exactly match the target database's column names (case-sensitive). Mismatched names will cause a 400 error. How to get valid property names: 1. Use "Query a Database" action to inspect the database schema 2. Check the database in Notion UI (column headers are property names) Common property types: Title (required in most databases): ``json { "Name": { "title": [{"text": {"content": "Page Title"}}] } } ` **Rich Text:** `json { "Description": { "rich_text": [{"text": {"content": "Some text"}}] } } ` **Select:** `json { "Status": { "select": {"name": "In Progress"} } } ` **Date:** `json { "Due Date": { "date": {"start": "2024-01-20"} } } ` **Number:** `json { "Priority": {"number": 5} } ` **Checkbox:** `json { "Completed": {"checkbox": true} } `` Example: {"Name": {"title": [{"text": {"content": "Project A"}}]}, "Status": {"select": {"name": "In Progress"}}}

Options:

• Children: Block objects array for page content (optional). Each block represents a content element. Common block types: Paragraph: ``json { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{"text": {"content": "Your text here"}}] } } ` **Heading 1:** `json { "object": "block", "type": "heading_1", "heading_1": { "rich_text": [{"text": {"content": "Section Title"}}] } } ` **To-do:** `json { "object": "block", "type": "to_do", "to_do": { "rich_text": [{"text": {"content": "Task description"}}], "checked": false } } `` Example: Pass an array of blocks to create structured content.

Output:

• Page (object): The complete page object returned by Notion API. Top-level fields: - id (string): Page unique identifier (UUID format) - created_time (string): ISO 8601 creation timestamp - last_edited_time (string): Last modification timestamp - url (string): Public URL of the page - archived (boolean): Archive status - parent (object): Parent database reference - parent.database_id (string): Parent database ID Properties object structure: - properties (object): All property values, keyed by property name - Each property contains: - id (string): Property ID - type (string): Property type (title, rich_text, select, date, etc.) - Type-specific value field (e.g., title, rich_text, select, date, number, checkbox) Example - Extracting values: - Title: Page.properties.Name.title[0].plain_text - Select: Page.properties.Status.select.name - Date: Page.properties[\"Due Date\"].date.start - Number: Page.properties.Priority.number - Checkbox: Page.properties.Completed.checkbox Full example in ResponseExample.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

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 unique identifier of the Notion page to retrieve. Must be a valid UUID-format string (32 characters with hyphens, e.g., 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'). You can obtain Page IDs from 'Search Pages in Database' or 'List Database Entries' actions, or copy from Notion web URL.

Output:

• Page (object): Notion page object containing full page metadata and properties. Core fields include: 'id' (string, unique page identifier), 'created_time' (string, ISO 8601 creation timestamp), 'last_edited_time' (string, ISO 8601 last edit timestamp), 'archived' (boolean, archive status), 'properties' (object, page properties vary by database schema), 'parent' (object, contains 'type' and 'database_id' or 'page_id'), 'url' (string, public URL of the page), 'cover' (object or null, page cover image), 'icon' (object or null, page icon), 'created_by' (object, user who created the page), 'last_edited_by' (object, user who last edited the page).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Database Pages

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

Input Parameters:

• DatabaseId: The unique identifier of the Notion database (32-character UUID without hyphens). How to get DatabaseId: 1. Open the database in Notion 2. Copy the page URL: https://www.notion.so/{workspace}/{database_id}?v=... 3. Extract the 32-character string before ?v= 4. Example: If URL is notion.so/myworkspace/a1b2c3d4e5f6...?v=123, DatabaseId is a1b2c3d4e5f6... Alternative: Use "List Databases" or "Search" action to get DatabaseId programmatically.

Options:

• PageSize: Maximum number of pages to return per request. Valid range: 1-100. Default is 50.
• StartCursor: Pagination cursor returned from previous response's NextCursor field. Leave empty for the first request. Usage pattern: 1. First call: Leave empty 2. Check response's HasMore field 3. If HasMore=true, use NextCursor value for next call 4. Repeat until HasMore=false
• Filter: Optional filter object to query specific pages. Follows Notion API filter syntax. Filter Structure: - Single condition: {"property": "PropertyName", "select": {"equals": "Value"}} - Multiple conditions (AND): {"and": [condition1, condition2, ...]} - Multiple conditions (OR): {"or": [condition1, condition2, ...]} Supported Property Types: - select/multi_select: {"property": "Status", "select": {"equals": "Done"}} - text: {"property": "Name", "text": {"contains": "Project"}} - number: {"property": "Price", "number": {"greater_than": 100}} - date: {"property": "Due", "date": {"after": "2024-01-01"}} - checkbox: {"property": "Completed", "checkbox": {"equals": true}} - people: {"property": "Assignee", "people": {"contains": "user-id"}} How to get user-id for people filter: 1. Use "Search Users" action to get user objects 2. Extract the "id" field from user object 3. Example user-id format: "user-123abc-456def-789ghi" Alternative: Use "List Database Users" to get all users with access to the database. Full filter syntax: https://developers.notion.com/reference/post-database-query-filter Leave empty to retrieve all pages without filtering.
• Sorts: Optional array to sort query results. Each sort object contains: - property (string): Property name to sort by - direction (string): "ascending" or "descending" Examples: - Single sort: [{"property": "Created", "direction": "descending"}] - Multiple sorts: [{"property": "Priority", "direction": "ascending"}, {"property": "Name", "direction": "ascending"}] Special sorts: - Sort by created time: [{"timestamp": "created_time", "direction": "descending"}] - Sort by last edited: [{"timestamp": "last_edited_time", "direction": "descending"}] Note: Sorts are applied in array order (first sort has highest priority). Leave empty to use Notion's default order.

Output:

• Pages (object-array): Array of Notion page objects matching the query. Each page object contains: - id (string): Unique page identifier (32-character UUID) - properties (object): Page properties (title, text, select, multi-select, date, number, checkbox, etc.) - created_time (string): ISO 8601 timestamp when page was created - last_edited_time (string): ISO 8601 timestamp when page was last edited - archived (boolean): Whether the page is archived - url (string): Public URL of the page - parent (object): Parent database reference - icon (object): Page icon (emoji or external URL) - cover (object): Page cover image Full page object structure: https://developers.notion.com/reference/page
• NextCursor (string): Pagination cursor for fetching the next page of results. Use this value in the StartCursor parameter for the next request. Empty string if no more results (HasMore=false).
• HasMore (bool): Indicates whether there are more results available. If true, use NextCursor to fetch the next page.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Update a Database Page

Updates properties of an existing Notion database page using the /v1/pages/{page_id} endpoint. Risk Level: Medium. This action writes changes to an existing page and has no dry-run mode; verify PageId and Properties before calling. Only provided properties are updated.

Input Parameters:

• PageId: The ID of the page to update (32-character UUID without hyphens). You can obtain PageId through: 1) Query a Database action (each page contains an 'id' field), 2) Search action (results include 'id' field), or 3) Extract from Notion page URL (remove hyphens from the 32-character ID). Example: 5f7a8b2c3d1e4f5a6b7c8d9e0f1a2b3c
• Properties: Page properties object (key-value pairs). Key is the Notion database field name, Value is the field value object conforming to Notion API format. This action uses PATCH method for partial update - only provided properties will be updated, others remain unchanged. Common Property Type Examples: - Title: {"Title": {"title": [{"text": {"content": "New Title"}}]}} - Rich Text: {"Description": {"rich_text": [{"text": {"content": "Some text"}}]}} - Number: {"Price": {"number": 99.99}} - Select: {"Status": {"select": {"name": "Done"}}} - Multi-select: {"Tags": {"multi_select": [{"name": "Important"}]}} - Date: {"DueDate": {"date": {"start": "2024-01-15"}}} - Checkbox: {"Completed": {"checkbox": true}} - URL: {"Website": {"url": "https://example.com"}} - Email: {"ContactEmail": {"email": "user@example.com"}} - Phone: {"Phone": {"phone_number": "+1-555-0100"}} For complete property formats, refer to Notion API documentation: https://developers.notion.com/reference/page Example: {"Title": {"title": [{"text": {"content": "Updated Page Title"}}]}, "Status": {"select": {"name": "In Progress"}}}

Output:

• UpdatedPage (object): The complete updated Notion page object returned by the API, containing the following core fields: - id (string): Unique page identifier - properties (object): Updated page properties collection - url (string): Page access URL - created_time (string): Creation time in ISO 8601 format - last_edited_time (string): Last edit time - parent (object): Parent container information (database_id or page_id) - archived (boolean): Whether the page is archived - icon (object|null): Page icon - cover (object|null): Page cover image For complete field list, refer to Notion API Page Object: https://developers.notion.com/reference/page
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Archive Page

Archives a Notion page by setting its archived status to true. ⚠️ Risk Level: Medium. Archived pages are hidden from workspace but CAN BE RESTORED via Notion UI (Settings & Members > Trash). This operation is reversible within 30 days.

Input Parameters:

• PageId: The unique identifier of the Notion page to archive. Format: 32-character UUID without hyphens (e.g., '1234567890abcdef1234567890abcdef'). You can obtain the Page ID from the page URL (last segment), or from outputs of 'Search Pages' or 'Get Page' actions.

Output:

• ArchivedPage (object): The archived page object returned by Notion API. Key fields include: - id (string): Page ID - object (string): Always 'page' - created_time (string): Page creation timestamp (ISO 8601) - last_edited_time (string): Last edit timestamp (ISO 8601) - archived (boolean): Archive status (should be true) - properties (object): Page properties - parent (object): Parent database or page info - url (string): Page URL in Notion workspace
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Create a Page

Creates a new page in Notion using the /v1/pages endpoint. Supports specifying parent type as database or page. Risk Level: Medium. This action creates new Notion content and is NOT idempotent; retrying after a timeout may create duplicate pages. Before retrying, search or inspect the parent/database to confirm whether the page already exists.

Input Parameters:

• ParentType: The type of parent. - 'database_id': Create a record in a structured database (like a row in a spreadsheet). Use cases: Task lists, customer CRM, project tracking. - 'page_id': Create a sub-page under an existing page (like a document section). Use cases: Meeting notes, documentation chapters, nested wikis. 💡 Tip: If you're organizing data with properties (Status, Priority, etc.), use 'database_id'. If you're writing long-form content, use 'page_id'.
• ParentId: To obtain: - Database ID from 'Search Databases' or 'Retrieve a Database' - Page ID from 'Search Pages' or extract from Notion page URL (URL format: https://notion.so/Page-Title-{PAGE_ID}, extract the 32-char ID after last hyphen) Example: - URL: https://notion.so/My-Page-a8d02e7f8be44f27a3e99c8b3e4d5f6a - Page ID: a8d02e7f-8be4-4f27-a3e9-9c8b3e4d5f6a (add hyphens at positions 8, 12, 16, 20)
• Properties: Page properties object matching Notion API's properties format. Required properties vary by parent type. When parent_type=database_id: Must include all required properties defined by the database (e.g., title). When parent_type=page_id: Must include 'title' property as page title. Common property types: (1) title (required): Page title. Format: {"title": {"title": [{"text": {"content": "My Page"}}]}}. (2) rich_text: Multi-line text. Format: {"Description": {"rich_text": [{"text": {"content": "Some text"}}]}}. (3) number: Numeric value. Format: {"Price": {"number": 100}}. (4) select: Single selection. Format: {"Status": {"select": {"name": "In Progress"}}}. (5) multi_select: Multiple selections. Format: {"Tags": {"multi_select": [{"name": "Tag1"}, {"name": "Tag2"}]}}. (6) date: Date value. Format: {"Due Date": {"date": {"start": "2024-01-15"}}}. Example: {"title": {"title": [{"text": {"content": "Q1 Project Plan"}}]}, "Status": {"select": {"name": "Active"}}, "Priority": {"number": 1}}

Options:

• Children: Array of block objects for page content (optional). Used to populate the page body. Each element is a block object. Common block types: (1) paragraph: Paragraph text. Format: {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}. (2) heading_1/2/3: Headings. Format: {"object": "block", "type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Section"}}]}}. (3) bulleted_list_item: Bullet list item. Format: {"object": "block", "type": "bulleted_list_item", "bulleted_list_item": {"rich_text": [{"text": {"content": "Item 1"}}]}}. (4) code: Code block. Format: {"object": "block", "type": "code", "code": {"language": "python", "rich_text": [{"text": {"content": "print('hello')"}}]}}. Example: [{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Project overview"}}]}}]
• Icon: Page icon configuration (optional). Supports emoji or external image URL. Emoji icon: {"type": "emoji", "emoji": "📄"}. External image: {"type": "external", "external": {"url": "https://example.com/icon.png"}}. Example: {"type": "emoji", "emoji": "🚀"}
• Cover: Page cover image configuration (optional). Supports external image URL only. Format: {"type": "external", "external": {"url": "https://example.com/cover.jpg"}}. Example: {"type": "external", "external": {"url": "https://images.unsplash.com/photo-123456"}}

Output:

• PageId (string): The unique identifier of the newly created page (32-character string with hyphens). Can be used for subsequent Update/Retrieve/Archive operations. Example: 'a8d02e7f-8be4-4f27-a3e9-9c8b3e4d5f6a'
• CreatedPage (object): The complete page object returned by Notion API, including: - id (string): Page ID - url (string): Page access link - created_time (string): Creation time (ISO 8601 format) - last_edited_time (string): Last edit time - properties (object): Page properties. Structure matches the input 'Properties' parameter. Each property contains: {id, type, [type-specific-value]} Example: {"Status": {"id": "abc", "type": "select", "select": {"name": "Active"}}} - parent (object): Parent information (database_id or page_id) - icon (object): Page icon (if set) - cover (object): Page cover (if set)
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Search a Page

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

Options:

• Query: Search keyword (optional). Performs full-text fuzzy matching against page titles and content. Leave empty to return all pages (use with Filter). Search rules: Case-insensitive, supports Chinese/English, no regex or wildcards. Example: "Project Plan"
• Sort: Sort condition object (optional). Common sort: Sort by last edited time in descending order: {"timestamp": "last_edited_time", "direction": "descending"}. Example: {"timestamp": "last_edited_time", "direction": "descending"}
• PageSize: Maximum number of items per page (optional). Default is 50, maximum is 100.
• StartCursor: Pagination cursor (optional). Leave empty for the first page. Use the NextCursor from the previous response to fetch the next page.

Output:

• Pages (object-array): List of page objects matching the search criteria. Each object contains: id (string): Unique page identifier, created_time (string): Creation time (ISO 8601), last_edited_time (string): Last edited time, url (string): Page link, properties (object): Page properties (title, etc.), parent (object): Parent page or database info.
• NextCursor (string): Cursor for fetching the next page of results. Empty if no more pages.
• HasMore (bool): Indicates whether more results are available. If true, use NextCursor in the next request.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

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. How to obtain: 1) Call 'List Users' action to get all workspace users; 2) Call 'Search Users' action to find specific users; 3) Copy from Notion page properties (Person field); 4) Extract from Notion API responses (e.g., page.created_by.id). Format: UUID string (e.g., 'b9e6e64e-1234-5678-abcd-1234567890ab').

Output:

• User (object): The user object returned by the Notion API, containing: object (string, always 'user'), id (string, unique user identifier in UUID format), type (string, either 'person' or 'bot'), name (string, full name of the user), avatar_url (string, URL to the user's profile picture), person (object, contains email field for person type users), bot (object, contains owner and workspace_name fields for bot type users). Example: {"object": "user", "id": "b9e6e64e-1234-5678-abcd-1234567890ab", "type": "person", "name": "John Doe", "avatar_url": "https://example.com/avatar.jpg", "person": {"email": "john@example.com"}}.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Users

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

Options:

• PageSize: Maximum number of users per page (1-1000). Default is 10. If you need all users, use 100 for better performance.
• StartCursor: Pagination cursor (opaque string, usually a UUID). Get this value from the 'NextCursor' field of the previous response. Leave empty for the first page. Example: "7c6b1c95-de50-45ca-b908-5e26cac3b3e6"

Output:

• Users (object-array): List of user objects returned by Notion API. Each user contains: - id (string): Unique user identifier (UUID format, e.g., "92a680bb-6970-4726-8b9c-757647f3cf44") - type (string): User type, usually 'person' or 'bot' - name (string): Display name of the user - avatar_url (string): Profile picture URL (may be null) - object (string): Always 'user' - person (object): Person details (only for type='person'), includes: - email (string): Email address - bot (object): Bot details (only for type='bot'), includes: - owner (object): Bot owner information - workspace_name (string): Workspace name Example: {"id": "92a680bb-6970-4726-8b9c-757647f3cf44", "type": "person", "name": "John Doe", "avatar_url": "https://example.com/avatar.jpg", "object": "user", "person": {"email": "john@example.com"}}
• NextCursor (string): Cursor for fetching the next page. Pass this value to the 'StartCursor' input parameter in the next request. Empty string means no more pages. Format: UUID string. Example: "7c6b1c95-de50-45ca-b908-5e26cac3b3e6"
• HasMore (bool): Indicates whether more results are available. If true, use NextCursor in the next request.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through a common automation scenario: Creating a new task in a Notion Database.

Scenario: You want to automatically add a new item (e.g., a task or a lead) to a specific Notion database.

Workflow Overview: Start -> Notion (Create a Database Page) -> Answer

Step-by-Step Guide:

1. Add the Tool Node:
   • In your workflow canvas, click the "+" button to add a new node.
   • Select the "Tools" tab.
   • Search for and select Notion.
   • From the list of operations, choose Create a Database Page.
2. Configure the Node:
   • Click the new Notion node to open its configuration panel.
   • Credentials: Select your configured Notion integration credential.
   • DatabaseId: Enter the ID of the database where you want to add the item.
   • Tip: Open your database in a browser. The ID is the 32-character string between the workspace name and the ? in the URL.
   • Properties: You must provide a JSON object defining the content of the new row. The keys must match your database column names exactly.
   • Example:

   {
     "Name": {
       "title": [
         {
           "text": {
             "content": "Review Q3 Report"
           }
         }
       ]
     },
     "Status": {
       "select": {
         "name": "To Do"
       }
     },
     "Priority": {
       "number": 1
     }
   }
   

3. Run and Verify:
   • Ensure all required fields are filled and the error indicator disappears.
   • Click "Run" in the top right corner.
   • Check the logs to see the output. You should receive a Page object with a new ID.
   • Open your Notion database to confirm the new row has been added.

Result: After completing these steps, your workflow will be able to programmatically insert new records into your Notion database.

6. FAQs

Q: Why do I get a "Database not found" or 404 error?

A: This is the most common issue. It usually happens because the integration hasn't been given access to that specific database.

• Open the database page in Notion.
• Click the ... menu in the top right corner.
• Scroll down to "Connections" (or "Add connections").
• Search for and select your integration name.

Q: My "Properties" JSON is causing an error.

A: The Notion API is strict about property formats.

• Ensure the keys in your JSON (e.g., "Name", "Status") match the column names in Notion exactly (case-sensitive).
• Ensure the structure matches the property type (e.g., a "Title" column requires a specific nested object structure, not just a string).

Q: How do I find the ID for a specific user?

A: You can use the Get Many Users action to list all users in the workspace and find the ID there. Alternatively, if you query a page that has a "Person" property filled in, the response will contain the user's ID.

7. Official Documentation

Notion Official API Documentation