# Notion

Workspace content on Notion — search pages and tables, read whole pages as Markdown, query table rows with structured filters, and manage pages, blocks, databases, and comments. Reads are free; writes (create/update/move/append/archive) are paid.

Run these through `omni-cli` once a human has connected the platform (`omni-cli notion login`). Full parameter and output schemas come from `omni-cli discovery notion`.

## blocks

| Command | What it does | Kind |
|---|---|---|
| `omni-cli notion block append` | Append content blocks to a page or block (default position is the end; use after to position). | write |
| `omni-cli notion block delete` | Delete (archive) a block — reversible via block.update archived=false. NOT retry-safe — re-deleting an already-archived block answers 400; unarchive first. | write |
| `omni-cli notion block get` | Get one block by id (its type names the block.update param to use). | read |
| `omni-cli notion block list` | List a block's direct children — pass a page id to list the page's top-level content blocks. | read |
| `omni-cli notion block update` | Update a block's content or archived state — pass EXACTLY the one type param matching the block's current type (block.get tells you; Notion rejects type changes). Re-sending the same content converges, so retries are safe. | write |

## comments

| Command | What it does | Kind |
|---|---|---|
| `omni-cli notion comment create` | Comment on a page (new discussion) or reply to an existing thread — pass EITHER page-id OR discussion-id, not both. | write |
| `omni-cli notion comment get` | Get one comment by id. | read |
| `omni-cli notion comment list` | List the open comments on a page or block — yields the discussion_id that threads replies through comment.create. | read |

## tables

| Command | What it does | Kind |
|---|---|---|
| `omni-cli notion database create` | Create a database (with its first table) under a page. | write |
| `omni-cli notion database get` | Get one database — THE discovery hop; its data_sources[] lists the database's tables, whose ids feed table.get, table.query, and page.create. | read |
| `omni-cli notion table get` | Get a table's schema (property definitions) — read this before building a table.query filter or page.create properties. | read |
| `omni-cli notion table query` | Query a table's rows with structured filters and sorts — the primary structured read; each result row IS a page. | read |

## pages

| Command | What it does | Kind |
|---|---|---|
| `omni-cli notion page append` | Append Markdown content to the end of a page (pairs with page.read). | write |
| `omni-cli notion page create` | Create a page under a table (as a row) or under a page (as a subpage) — pass EITHER parent-table-id OR parent-page-id, not both. | write |
| `omni-cli notion page get` | Get one page's metadata and property VALUES (not content — page.read returns the content as Markdown). | read |
| `omni-cli notion page get-property` | Get one page property's paginated values — needed for relations/rollups longer than 25 items, which page.get truncates. | read |
| `omni-cli notion page move` | Move a page under a new parent table or page — pass EITHER parent-table-id OR parent-page-id, not both. Re-moving to the same parent converges, so retries are safe. | write |
| `omni-cli notion page read` | Read a whole page's content as Markdown — the primary agent read surface (pairs with page.append/page.replace). | read |
| `omni-cli notion page replace` | Replace a page's Markdown content when find matches existing content — replaces the WHOLE page content, not just the match, so read first with page.read. Converges on retry (a second identical call is a no-op 200). | write |
| `omni-cli notion page search` | Search the workspace by title — returns pages AND tables (object: page \| data_source) that have been shared with the integration; the discovery entry point for every page and database id. | read |
| `omni-cli notion page update` | Update a page's property values or archive/restore it — archive is THE cleanup verb (Notion has no hard delete). Setting the same values again converges, so retries are safe. | write |

## users

| Command | What it does | Kind |
|---|---|---|
| `omni-cli notion user get` | Get one user by id (requires the integration's user-information capability — 403 without it). | read |