# Notion tools (https://www.shipfox.io/docs/integrations/notion/tools)

Description: Look up the eight Notion tools, selectors, access boundaries, inputs, and outputs available to workflows.

This reference lists the eight shipped Notion tools. See the [Notion
overview](https://www.shipfox.io/docs/integrations/notion) for authentication and access boundaries.

## Permissions [#permissions]

Notion tools can access only pages shared with the integration connection.
Sharing a parent page also shares its child pages.

Read tools need read access to the target page. Write tools need the matching
Notion content or comment capability. Agent steps must also set `allow_write:
true`. A tool step opts into a write by naming that tool directly.

For tool step and agent integration fields, see the [workflow schema
reference](https://www.shipfox.io/docs/reference/workflow-schema#tool-step-fields).

## Read a page from an event [#read-a-page-from-an-event]

Notion events contain IDs instead of current page values. Add this fragment
under an existing job's `steps` list to fetch the current page:

```yaml
- key: page
  tool: get_page
  connection: notion_acme # Replace with your Notion integration connection slug.
  with:
    page_id: ${{ event.entity.id }}
```

The `get_page` result becomes available as `steps.page.outputs.result`.

## Tool catalog [#tool-catalog]

### Tools

#### `search`

Search shared Notion pages and data sources by title. This is not full-text search. The result is paginated and can be filtered by object type.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `search`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | Optional | Title text to search for |
| `object` | string: `page`, `data_source` | Optional | Only return pages or data sources |
| `page_size` | integer | Optional | Number of results to return, from 1 to 100 Minimum 1. Maximum 100. |
| `cursor` | string | Optional | Notion pagination cursor from the previous response |

##### Output

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | array of object | Optional |  |
| `next_cursor` | string \| null | Optional | Cursor for the next page |
| `has_more` | boolean | Optional | Whether another page is available |

#### `get_page`

Retrieve a shared Notion page by URL or ID, including its title, parent, properties, and timestamps.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `get_page`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `page_id` | string | Required | Notion page URL or page ID |

##### Output

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | Optional | Notion page ID |
| `url` | string | Optional | Notion page URL |
| `title` | string | Optional | Page title |
| `parent` | object | Optional | Notion object with provider-defined fields |
| `properties` | object | Optional | Notion object with provider-defined fields |
| `created_time` | string | Optional | Creation timestamp |
| `last_edited_time` | string | Optional | Last edit timestamp |

#### `get_page_content`

Retrieve the Markdown content of a shared Notion page by URL or ID.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `get_page_content`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `page_id` | string | Required | Notion page URL or page ID |

##### Output

| Field | Type | Required | Description |
|---|---|---|---|
| `markdown` | string | Optional | Page content in Markdown |
| `truncated` | boolean | Optional | Whether Notion truncated the content |
| `unknown_block_ids` | array of string | Optional |  |

#### `query_data_source`

Query rows in a shared Notion data source. Notion filter and sort objects pass through unchanged.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `query_data_source`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `data_source_id` | string | Required | Notion data source URL or data source ID |
| `filter` | object | Optional | Notion object with provider-defined fields |
| `sorts` | array of object | Optional |  |
| `page_size` | integer | Optional | Number of results to return, from 1 to 100 Minimum 1. Maximum 100. |
| `cursor` | string | Optional | Notion pagination cursor from the previous response |

##### Output

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | array of object | Optional |  |
| `next_cursor` | string \| null | Optional | Cursor for the next page |
| `has_more` | boolean | Optional | Whether another page is available |

#### `get_comments`

List comments on a shared Notion page or block. The result is paginated.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `get_comments`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `block_id` | string | Required | Notion page URL, block URL, or block ID |
| `cursor` | string | Optional | Notion pagination cursor from the previous response |

##### Output

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | array of object | Optional |  |
| `next_cursor` | string \| null | Optional | Cursor for the next page |
| `has_more` | boolean | Optional | Whether another page is available |

#### `create_page`

Create a Notion page under a page or data source. Properties use Notion's shape and markdown is optional. Notion limits each rich text item to 2,000 characters, block arrays to 100 items, and each request to 500 KB.

**Access:** write.

**Sensitive:** No.

**Required permissions:** `write`

**Selector tokens:** `create_page`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `parent` | object | Required | Notion page or data source parent, with page_id or data_source_id |
| `properties` | object | Required | Notion page properties in Notion's property shape |
| `markdown` | string | Optional | Markdown page content |

##### Output

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | Optional | Notion page ID |
| `url` | string | Optional | Notion page URL |
| `title` | string | Optional | Page title |
| `parent` | object | Optional | Notion object with provider-defined fields |
| `properties` | object | Optional | Notion object with provider-defined fields |
| `created_time` | string | Optional | Creation timestamp |
| `last_edited_time` | string | Optional | Last edit timestamp |

#### `update_page`

Update a Notion page properties and/or its Markdown content. Properties are updated first when both are provided; content mode is append or replace. Notion limits each rich text item to 2,000 characters, block arrays to 100 items, and each request to 500 KB.

**Access:** write.

**Sensitive:** No.

**Required permissions:** `write`

**Selector tokens:** `update_page`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `page_id` | string | Required | Notion page URL or page ID |
| `properties` | object | Optional | Notion page properties in Notion's property shape |
| `markdown` | string | Optional | Markdown page content |
| `mode` | string: `append`, `replace` | Optional | Whether to append or replace Markdown content |

##### Output

This tool returns the provider response without declared fields.

#### `add_comment`

Add plain text to a Notion page or reply to a discussion. Text over 2,000 characters is split into multiple rich text items. Notion limits block arrays to 100 items and each request to 500 KB.

**Access:** write.

**Sensitive:** No.

**Required permissions:** `write`

**Selector tokens:** `add_comment`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `page_id` | string | Optional | Notion page URL or page ID |
| `discussion_id` | string | Optional | Notion discussion ID for a reply |
| `text` | string | Required | Plain-text comment content |

##### Output

This tool returns the provider response without declared fields.