# Notion on boxd

> Notion centralizes notes, docs, wikis, and tasks in a unified workspace, letting teams build custom workflows for collaboration and knowledge management.

- Page: https://boxd.sh/integrations/notion/
- CLI: `run notion` (56 commands, 39 marked common)
- SDK: `import { notion } from "@boxd/run"`; every parameter and response type is at `@boxd/run/notion`
- Triggers: 8
- Connect: `run auth notion` (Sign in with Notion), or https://app.boxd.sh/integrations/detail/notion
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth notion      # once: prints a link to connect your account
run notion           # list its commands
run notion list-users
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { notion } from "@boxd/run";

const result = await notion.listUsers({});
console.log(result);

notion.on("comment-created", async (event) => {
  // Comment Created: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run notion.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run notion <command> --help` lists the optional ones. "common" marks what `run notion` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-multiple-page-content` ·common | `notion.addMultiplePageContent()` | `--content-blocks` `--parent-block-id` | 1 | Bulk-add content blocks to Notion |
| `add-page-content` ·deprecated | `notion.addPageContent()` | `--content-block` `--parent-block-id` | 1 | Use 'add_multiple_page_content' for better performance |
| `append-block-children` ·deprecated | `notion.appendBlockChildren()` | `--block-id` `--children` | 1 | Use append-text-blocks, append-task-blocks, append-code-blocks, append-media-blocks, append-layout-blocks, or append-table-blocks instead |
| `append-code-blocks` | `notion.appendCodeBlocks()` | `--block-id` `--children` | 1 | Append code and technical blocks (code, quote, equation) to a Notion page |
| `append-layout-blocks` | `notion.appendLayoutBlocks()` | `--block-id` `--children` | 1 | Append layout blocks (divider, TOC, breadcrumb, columns) to a Notion page |
| `append-media-blocks` | `notion.appendMediaBlocks()` | `--block-id` `--children` | 1 | Append media blocks (image, video, audio, file, pdf, embed, bookmark) to a Notion page |
| `append-table-blocks` | `notion.appendTableBlocks()` | `--block-id` `--tables` | 1 | Append table blocks to a Notion page |
| `append-task-blocks` | `notion.appendTaskBlocks()` | `--block-id` `--children` | 1 | Append task blocks (to-do, toggle, callout) to a Notion page or block |
| `append-text-blocks` | `notion.appendTextBlocks()` | `--block-id` `--children` | 1 | Append text blocks (paragraphs, headings, lists) to a Notion page |
| `archive-page` | `notion.archivePage()` | `--page-id` | 1 | Archives (moves to trash) or unarchives (restores from trash) a specified Notion page |
| `create-comment` ·common | `notion.createComment()` | `--comment` | 2 | Adds a comment to a Notion page (via `parent_page_id`) OR to an existing discussion thread (via `discussion_id`); cannot create new discussion threads on specific blocks (inline comments) |
| `create-database` ·common | `notion.createDatabase()` | `--parent-id` `--title` | 1 | Creates a new Notion database as a subpage under a specified parent page with a defined properties schema |
| `create-file-upload` | `notion.createFileUpload()` | — | 5 | Create a Notion FileUpload object and retrieve an upload URL |
| `create-page` ·common | `notion.createPage()` | `--parent-id` `--title` | 3 | Creates a new page in a Notion workspace under a specified parent page or database |
| `create-view` ·common | `notion.createView()` | `--data-source-id` `--name` `--type` | 9 | Create a Notion view |
| `create-view-query` ·common | `notion.createViewQuery()` | `--view-id` | 1 | Create a Notion view query and return the first page of page references |
| `delete-block` ·common | `notion.deleteBlock()` | `--block-id` | 0 | Archives a Notion block, page, or database using its ID, which sets its 'archived' property to true (like moving to "Trash" in the UI) and allows it to be restored later |
| `delete-view` ·common | `notion.deleteView()` | `--view-id` | 0 | Delete a Notion view |
| `delete-view-query` ·common | `notion.deleteViewQuery()` | `--query-id` `--view-id` | 0 | Delete a cached Notion view query |
| `duplicate-page` | `notion.duplicatePage()` | `--page-id` `--parent-id` | 1 | Duplicates a Notion page, including all its content, properties, and nested blocks, under a specified parent page or workspace |
| `fetch-all-block-contents` ·common | `notion.fetchAllBlockContents()` | — | 6 | Fetch all child blocks for a given Notion block |
| `fetch-block-contents` ·common | `notion.fetchBlockContents()` | `--block-id` | 2 | Retrieves a paginated list of direct, first-level child block objects along with contents for a given parent Notion block or page ID; use block IDs from the response for subsequent calls to access… |
| `fetch-block-metadata` | `notion.fetchBlockMetadata()` | `--block-id` | 0 | Fetches metadata for a Notion block (including pages, which are special blocks) using its UUID |
| `fetch-comments` ·common | `notion.fetchComments()` | — | 4 | Fetches unresolved comments for a specified Notion block or page ID |
| `fetch-data` | `notion.fetchData()` | `--fetch-type` | 5 | Fetches Notion items (pages and/or databases) from the Notion workspace, use this to get minimal data about the items in the workspace with a query or list all items in the workspace with minimal data |
| `fetch-database` ·common | `notion.fetchDatabase()` | `--database-id` | 0 | Fetches a Notion database's structural metadata (properties, title, etc.) via its `database_id`, not the data entries; `database_id` must reference an existing database |
| `fetch-row` ·common | `notion.fetchRow()` | `--page-id` | 0 | Retrieves a Notion database row's properties and metadata; use fetch_block_contents for page content blocks |
| `get-about-me` ·common ·deprecated | `notion.getAboutMe()` | — | 0 | Use GetAboutUser instead |
| `get-about-user` ·common | `notion.getAboutUser()` | `--user-id` | 0 | Retrieves detailed information about a specific Notion user, such as their name, avatar, and email, based on their unique user ID |
| `get-page-markdown` ·common | `notion.getPageMarkdown()` | `--page-id` | 1 | Retrieve a Notion page's full content rendered as Notion-flavored Markdown in a single API call |
| `get-page-property-action` | `notion.getPagePropertyAction()` | `--page-id` `--property-id` | 2 | Call this to get a specific property from a Notion page when you have a valid `page_id` and `property_id`; handles pagination for properties returning multiple items |
| `get-view-query-results` ·common | `notion.getViewQueryResults()` | `--query-id` `--view-id` | 2 | Get a page of results from a cached Notion view query |
| `insert-row-database` ·common | `notion.insertRowDatabase()` | `--database-id` | 4 | Creates a new page (row) in a specified Notion database |
| `insert-row-from-nl` ·common | `notion.insertRowFromNl()` | `--database-id` `--nl-query` | 2 | Creates a new row (page) in a Notion database from a natural language description |
| `list-data-source-templates` | `notion.listDataSourceTemplates()` | `--data-source-id` | 2 | List all templates for a Notion data source |
| `list-file-uploads` | `notion.listFileUploads()` | — | 2 | Retrieve file uploads for the current bot integration, sorted by most recent first |
| `list-users` ·common | `notion.listUsers()` | — | 2 | Retrieves a paginated list of users (excluding guests) from the Notion workspace; the number of users returned per page may be less than the requested `page_size` |
| `list-views` ·common | `notion.listViews()` | — | 4 | List Notion views for a database or data source |
| `move-page` ·common | `notion.movePage()` | `--page-id` `--parent` | 0 | Move a Notion page to a new parent (page or database) |
| `query-data-source` ·common | `notion.queryDataSource()` | `--data-source-id` | 5 | Query a Notion data source |
| `query-database` ·common | `notion.queryDatabase()` | `--database-id` | 3 | Queries a Notion database to retrieve pages (rows) |
| `query-database-with-filter` ·common | `notion.queryDatabaseWithFilter()` | `--database-id` | 5 | Query a Notion database with server-side filtering, sorting, and pagination |
| `replace-page-content` ·common | `notion.replacePageContent()` | `--new-children` `--page-id` | 5 | Safely replaces a page's child blocks by optionally backing up current content, deleting existing children, then appending new children in batches |
| `retrieve-comment` ·common | `notion.retrieveComment()` | `--comment-id` | 0 | Retrieve a specific comment by its ID |
| `retrieve-database-property` ·common | `notion.retrieveDatabaseProperty()` | `--database-id` `--property-id` | 0 | Retrieve a specific property object of a Notion database |
| `retrieve-file-upload` ·common | `notion.retrieveFileUpload()` | `--file-upload-id` | 0 | Retrieve details of a Notion File Upload object by its identifier |
| `retrieve-page` ·common | `notion.retrievePage()` | `--page-id` | 0 | Retrieve a Notion page's properties/metadata (not block content) by page_id |
| `retrieve-view` ·common | `notion.retrieveView()` | `--view-id` | 0 | Retrieve a Notion view and its configuration |
| `search-page` ·common | `notion.searchPage()` | — | 8 | Searches Notion pages and databases by title |
| `send-file-upload` ·common | `notion.sendFileUpload()` | `--file` `--file-upload-id` | 2 | Transmit file contents to Notion for a file upload object |
| `update-block` | `notion.updateBlock()` | `--block-id` `--content` | 3 | Updates existing Notion block's text content. ⚠️ CRITICAL: Content limited to 2000 chars |
| `update-page` ·common | `notion.updatePage()` | `--page-id` | 4 | Update page properties, icon, cover, or archive status |
| `update-row-database` ·common | `notion.updateRowDatabase()` | `--row-id` | 4 | Updates a specific row/page within a Notion database by its page UUID (row_id) |
| `update-schema-database` ·common | `notion.updateSchemaDatabase()` | `--database-id` | 3 | Updates an existing Notion database's schema including title, description, and/or properties (columns) |
| `update-view` ·common | `notion.updateView()` | `--view-id` | 5 | Update a Notion view |
| `upsert-row-database` ·common | `notion.upsertRowDatabase()` | `--items` | 3 | Upsert rows in a Notion database by querying for existing rows and creating or updating them |

## Triggers

`notion.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"comment-created"` | Comment Created | — | Triggers when a new comment is created in Notion |
| `"database-created"` | Database Created | — | Triggers when a new Notion database (the container) is created |
| `"datasource-created"` | Data Source Created | — | Triggers when a new Notion data source is created |
| `"datasource-schema-updated"` | Data Source Schema Updated | — | Triggers when a Notion data source's schema is updated |
| `"page-content-updated"` | Page Content Updated | — | Triggers when the body content of a Notion page is updated |
| `"page-created"` | Page Created | — | Triggers when a new Notion page is created |
| `"page-properties-updated"` | Page Properties Updated | — | Triggers when properties of a Notion page are updated |
| `"view-created"` | View Created | — | Triggers when a new Notion view is created |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.