Block

The Block component lets you work directly with the building blocks of a Notion page.
You can create new blocks, delete existing ones, list all blocks on a page, or paste Markdown text that the component turns into Notion blocks.
It talks to the Notion API, so you’ll need a Notion integration token set up in Nappai first.

How it Works

When you use the component, Nappai sends a request to the Notion API.

• Create builds a new block under a specified page or block.
• Delete removes a block by its ID.
• List pulls all child blocks of a page or block.
• Add Markdown converts Markdown text into one or more Notion blocks and inserts them.

The component can also run in Mapping Mode, which lets you feed a list of records and have the component perform the chosen operation on each record automatically.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

• Create: Create a new block under a page or block.
• Delete: Delete a block by its ID.
• List: Retrieve all child blocks of a page or block.
• Add Markdown: Convert Markdown text into Notion blocks and add them to a page.

To use the component, first select the operation you need in the Operation field.

Inputs

Mapping Mode

This component has a special mode called Mapping Mode. When you enable this mode using the toggle switch, an additional input called Mapping Data is activated, and each input field offers you three different ways to provide data:

• Fixed: You type the value directly into the field.
• Mapped: You connect the output of another component to use its result as the value.
• Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

• Operation: Choose which action the component will perform.

  • Visible in: Create, Delete, List, Add Markdown

• Block ID: Target block ID for single‑block operations.

  • Visible in: Delete

• Select block type: Pick the type of block to create (e.g., paragraph, heading, list).

  • Visible in: Create

• Children: The children of the new block as a JSON string.

  • Visible in: Create

• Markdown Text: The markdown text to convert to Notion blocks or the content to add to the page.

  • Visible in: Add Markdown

• Parent Page ID: Notion Page ID or Block ID where the new block will be created.

  • Visible in: Create, List, Add Markdown

• Mapping Mode: Enable mapping mode to process multiple data records in batch.

  • Visible in: Create, Delete, List, Add Markdown

• Credential: Select a pre‑configured Notion API credential.

  • Visible in: Create, Delete, List, Add Markdown

• Tool Name: The name of the tool that will be used when this component is connected as a tool.

  • Visible in: Create, Delete, List, Add Markdown

• Tool Description: A detailed description of what this tool does.

  • Visible in: Create, Delete, List, Add Markdown

• Tools arguments metadata: Defines the arguments metadata for the tools.

  • Visible in: Create, Delete, List, Add Markdown

Credential setup

1. In Nappai, go to the Credentials section and add a new Notion API credential.
2. Provide the Notion Integration Token (you can create one in the Notion developer portal).
3. In the component, choose this credential from the Credential dropdown.

Outputs

• Data: The raw data returned from the Notion API (e.g., block details, list of blocks).
• Tool: A tool representation that can be used by Nappai agents to call this component programmatically.

Usage Example

1. Create a new paragraph block

1. Set Operation to Create.
2. Enter the Parent Page ID of the page where you want the block.
3. Choose Select block type → paragraph.
4. In Children, paste {"text":[{"content":"Hello, world!"}]}.
5. Click Run.
   The component will add a new paragraph block with the text “Hello, world!” to the specified page.

2. Add Markdown to a page

1. Set Operation to Add Markdown.
2. Enter the Parent Page ID.
3. Paste Markdown into Markdown Text (e.g., # Title\n\n- Item 1\n- Item 2).
4. Click Run.
   The component converts the Markdown into Notion blocks and inserts them.

3. Delete a block

1. Set Operation to Delete.
2. Enter the Block ID of the block you want to remove.
3. Click Run.
   The block is deleted from Notion.

4. List all blocks on a page

1. Set Operation to List.
2. Enter the Parent Page ID.
3. Click Run.
   The component returns a list of all child blocks, which you can use in subsequent steps.

5. Mapping Mode (Batch delete)

1. Enable Mapping Mode.
2. In Mapping Data, provide a JSON array of block IDs.
3. Set Operation to Delete.
4. Click Run.
   The component deletes each block in the array.

Related Components

• NotionDatabase – Manage Notion databases (create, read, update, delete).
• NotionSearch – Search for pages or blocks across your workspace.
• NotionSync – Keep local data in sync with Notion.

Tips and Best Practices

• Use Mapping Mode when you need to process many blocks at once; it saves time and reduces API calls.
• Keep your Notion Integration Token secret—never share it in public workflows.
• Validate JSON for the Children field to avoid errors; you can test it in a JSON validator before pasting.
• Check block limits: Notion allows a maximum of 100 blocks per page; if you exceed this, the component will return an error.
• Use the Tool outputs when integrating with Nappai agents; this lets agents decide when to call the component automatically.

Security Considerations

• The component uses your Notion Integration Token, so only users with access to that credential can perform actions.
• Ensure the credential is stored securely in Nappai’s credential store.
• When enabling Mapping Mode, be careful not to expose sensitive data in the mapping data payload.