@bitefoundry/notion 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 BiteFoundry
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 BiteFoundry
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,141 +1,152 @@
1
- <div align="center">
2
-
3
- # `@bitefoundry/notion`
4
-
5
- **Notion-native terminal workspace & AI agent toolkit — Editorial Pages, Interactive Blocks, Databases (Table/Board/List), CLI · TUI · HTTP API · MCP.**
6
-
7
- [![npm version](https://img.shields.io/npm/v/%40bitefoundry%2Fnotion?style=flat-square&color=191919)](https://www.npmjs.com/package/@bitefoundry/notion)
8
- [![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-24292F?style=flat-square)](docs/NPM.md)
9
- [![Rust & Ratatui](https://img.shields.io/badge/built%20with-Rust%20%2B%20Ratatui-DEA584?style=flat-square&logo=rust)](https://github.com/BiteFoundry/notion/blob/master/Cargo.toml)
10
- [![License: MIT](https://img.shields.io/badge/license-MIT-00875A?style=flat-square)](package.json)
11
-
12
- <br />
13
-
14
- ![Notion TUI Demo](https://raw.githubusercontent.com/BiteFoundry/notion/master/assets/demo.gif)
15
-
16
- </div>
17
-
18
- ---
19
-
20
- ## Highlights
21
-
22
- | Pillar | Capabilities |
23
- | :--- | :--- |
24
- | **Minimal-Chrome TUI** | Authentic Notion editorial aesthetic (`notion`): 1-line **Breadcrumb Bar**, collapsible **Workspace Sidebar (`[`)** with Favorites & nested tree, **Centered (~88 col) / Full Width (`w`) Page Canvas**, 10 canonical Notion pill colors, live interactive **`to_do` checkboxes (`Space`/`x`)** & **`toggle` blocks**, **Database Table (`1`) / Board Kanban (`2`) / List (`3`) views**, **Comments Peek Drawer (`C`)**, **Quick Find (`Ctrl+K`)**, **Multi-Workspace Switcher (`Ctrl+S`)**, and **5 curated palettes** (`Clean Dark`, `Warm Paper`, `Tokyo Night`, `Catppuccin`, `Nord`). |
25
- | **High-Res Terminal Images** | Native inline image previews for Notion-hosted & external media via **Kitty Graphics**, **iTerm2**, **Sixel**, and **24-bit Truecolor Half-Block (`▀`)** fallback (`v` HD modal & `notion download`). |
26
- | **Local SQLite FTS5 + IPC Daemon** | Workspace-scoped SQLite WAL + FTS5 cache (`pages`, `databases`, `blocks`, `comments`, `pages_fts`) with automatic `<3`-char Korean/CJK `LIKE` fallback, plus single-instance background sync IPC daemon (`notion daemon start`). |
27
- | **4-in-1 Agent Interface** | Same binary powers the **Interactive TUI**, scriptable **`--json` CLI**, local **HTTP JSON API** (`notion serve`, `:8791`), and **stdio MCP server** (`notion mcp`, **19 typed tools** with `confirm: true` archive guard). |
28
-
29
- ---
30
-
31
- ## Quick Start
32
-
33
- Upgrading from 0.1.x? Change `nt` to `notion` in shell scripts and set the MCP server’s `command` to `notion`.
34
-
35
- ```bash
36
- # 1. Install globally (installs the native `notion` command)
37
- npm i -g @bitefoundry/notion
38
-
39
- # 2. Authenticate — Internal Integration Token (30-second setup) or Public OAuth 2.0
40
- notion login --token ntn_...
41
- # Or Public OAuth 2.0 loopback:
42
- notion login --oauth --client-id "$NOTION_CLIENT_ID" --client-secret "$NOTION_CLIENT_SECRET"
43
-
44
- # 3. Sync your workspace & launch the Notion-native TUI
45
- notion sync
46
- notion
47
- ```
48
-
49
- ---
50
-
51
- ## Keybindings Cheat Sheet
52
-
53
- | Key | Action | Context |
54
- | :--- | :--- | :--- |
55
- | `[` / `Ctrl+B` | Toggle collapsible Workspace Sidebar | Global |
56
- | `Tab` / `Shift+Tab` | Cycle focus across Sidebar, Canvas, and Comments Drawer | Global |
57
- | `j` `k` / `↑` `↓` | Move across sidebar tree, page blocks, or database rows | Global |
58
- | `Space` / `x` | Check/uncheck live `to_do` block or expand/collapse `toggle` block | Page Canvas |
59
- | `w` / `f` / `y` | Toggle Centered vs Full Width / Favorite star / Copy code block | Page Canvas |
60
- | `a` / `n` / `e` | Slash Quick Append (`/h1`, `/todo`, `/callout`) / New Page / `$EDITOR` | Page / Database |
61
- | `C` | Toggle right-split Comments Peek Drawer & reply inline | Page Canvas |
62
- | `1` / `2` / `3` | Switch Database views: **Table** / **Board (Kanban)** / **List** | Database |
63
- | `f` / `s` / `m` | Filter rows / Cycle sort / Move Kanban card to another Status column | Database |
64
- | `Ctrl+K` / `Ctrl+P` | Quick Find & Command Palette (FTS5 search + workspace commands) | Global |
65
- | `u` / `Ctrl+F` / `v` | Link Extractor / File Picker (`z` zoxide) / HD Image Preview | Global |
66
- | `Ctrl+S` / `Ctrl+,` / `?` | Switch Workspace / Settings & Palettes / Keyboard Shortcuts Help | Global |
67
-
68
- ---
69
-
70
- ## CLI, HTTP API & MCP
71
-
72
- ### CLI (`--json` ready)
73
-
74
- ```bash
75
- # Search, read, append & export Notion pages
76
- notion search "Q4 Roadmap" --json
77
- notion pages list --json
78
- notion pages get "Q4 Launch Plan"
79
- notion pages get "Q4 Launch Plan" --json
80
- notion pages get "Q4 Launch Plan" --json --full
81
- notion pages edit "Q4 Launch Plan" --editor
82
- notion pages append "Q4 Launch Plan" "/todo Tag v1.0 release"
83
- notion pages export "Q4 Launch Plan" --out launch-plan.md
84
- notion blocks edit <block-id> --text "Release **verified**" --json
85
- notion blocks toggle <block-id>
86
-
87
- # Query & create Notion database items
88
- notion db list --json
89
- notion db query "Q4 Roadmap" --json
90
- notion db create-item "Q4 Roadmap" --title "Ship v1.0" --status "In Progress"
91
- notion comments list "Q4 Launch Plan" --json --limit 50 --cursor <next_cursor>
92
- notion comments add "Q4 Launch Plan" "Green light for launch!"
93
- notion download <url-or-block-id> --json
94
-
95
- # Multi-workspace profiles & background sync daemon
96
- notion workspaces list
97
- notion workspaces add work --token ntn_...
98
- notion workspaces use work
99
- notion daemon start
100
- ```
101
-
102
- ### Local HTTP JSON API (`notion serve`)
103
-
104
- ```bash
105
- notion serve --host 127.0.0.1 --port 8791 --api-key "$API_TOKEN"
106
- curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8791/api/v1/search?q=Roadmap"
107
- ```
108
-
109
- Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
110
-
111
- ### MCP Server (`notion mcp` — 19 Tools)
112
-
113
- ```json
114
- {
115
- "mcpServers": {
116
- "notion": {
117
- "command": "notion",
118
- "args": ["mcp"]
119
- }
120
- }
121
- }
122
- ```
123
-
124
- Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
125
-
126
- ---
127
-
128
- ## `@bitefoundry` Enterprise Terminal Suite
129
-
130
- | Package | Commands | Workspace | Interfaces |
131
- | :--- | :--- | :--- | :--- |
132
- | [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
133
- | [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
134
- | [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
135
- | [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `bitefoundry-onedrive` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
136
- | [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
137
- | **`@bitefoundry/notion`** | `notion` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
138
-
139
- ---
140
-
141
- > **Disclaimer:** Unofficial terminal client for Notion. Not affiliated with, endorsed by, or sponsored by Notion Labs, Inc.
1
+ <div align="center">
2
+
3
+ # `@bitefoundry/notion`
4
+
5
+ **Read and edit Notion pages, work with database records, and search a synced workspace from the terminal.**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/%40bitefoundry%2Fnotion?style=flat-square&color=191919)](https://www.npmjs.com/package/@bitefoundry/notion)
8
+ [![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-24292F?style=flat-square)](docs/NPM.md)
9
+ [![Rust & Ratatui](https://img.shields.io/badge/built%20with-Rust%20%2B%20Ratatui-DEA584?style=flat-square&logo=rust)](https://github.com/BiteFoundry/notion/blob/master/Cargo.toml)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-00875A?style=flat-square)](LICENSE)
11
+
12
+ [BiteFoundry](https://bitefoundry.dev/#app-notion) · [Latest release notes](https://github.com/BiteFoundry/notion/releases/latest)
13
+
14
+ <br />
15
+
16
+ ![Notion TUI Demo](https://raw.githubusercontent.com/BiteFoundry/notion/master/assets/demo.gif)
17
+
18
+ </div>
19
+
20
+ ---
21
+
22
+ ## Highlights
23
+
24
+ | Pillar | Capabilities |
25
+ | :--- | :--- |
26
+ | **Minimal-Chrome TUI** | Authentic Notion editorial aesthetic (`notion`): 1-line **Breadcrumb Bar**, collapsible **Workspace Sidebar (`[`)** with Favorites & nested tree, **Centered (~88 col) / Full Width (`w`) Page Canvas**, 10 canonical Notion pill colors, live interactive **`to_do` checkboxes (`Space`/`x`)** & **`toggle` blocks**, **Database Table (`1`) / Board Kanban (`2`) / List (`3`) views**, **Comments Peek Drawer (`C`)**, **Quick Find (`Ctrl+K`)**, **Multi-Workspace Switcher (`Ctrl+S`)**, and **5 curated palettes** (`Clean Dark`, `Warm Paper`, `Tokyo Night`, `Catppuccin`, `Nord`). |
27
+ | **High-Res Terminal Images** | Native inline image previews for Notion-hosted & external media via **Kitty Graphics**, **iTerm2**, **Sixel**, and **24-bit Truecolor Half-Block (`▀`)** fallback (`v` HD modal & `notion download`). |
28
+ | **Local SQLite FTS5 + IPC Daemon** | Workspace-scoped SQLite WAL + FTS5 cache (`pages`, `databases`, `blocks`, `comments`, `pages_fts`) with automatic `<3`-char Korean/CJK `LIKE` fallback, plus single-instance background sync IPC daemon (`notion daemon start`). |
29
+ | **4-in-1 Agent Interface** | Same binary powers the **Interactive TUI**, scriptable **`--json` CLI**, local **HTTP JSON API** (`notion serve`, `:8791`), and **stdio MCP server** (`notion mcp`, **20 typed tools** with `confirm: true` archive guard). |
30
+
31
+ ---
32
+
33
+ ## Quick Start
34
+
35
+ Upgrading from 0.1.x? Change `nt` to `notion` in shell scripts and set the MCP server’s `command` to `notion`.
36
+
37
+ ```bash
38
+ # 1. Install globally (installs the native `notion` command)
39
+ npm i -g @bitefoundry/notion
40
+
41
+ # 2. Authenticate — Internal Integration Token (30-second setup) or Public OAuth 2.0
42
+ notion login --token ntn_...
43
+ # Or Public OAuth 2.0 loopback:
44
+ notion login --oauth --client-id "$NOTION_CLIENT_ID" --client-secret "$NOTION_CLIENT_SECRET"
45
+
46
+ # 3. Sync your workspace & launch the Notion-native TUI
47
+ notion sync
48
+ notion
49
+ ```
50
+
51
+ ```sh
52
+ notion pages get PAGE_ID --json
53
+ ```
54
+
55
+ Read page Markdown and see which blocks or comments were loaded. A compact read skips the comments request. Use `notion comments list PAGE_ID --json` to fetch comments separately. For full detail, add `--full` in the CLI or pass `compact: false` to `get_page` in MCP.
56
+
57
+ ---
58
+
59
+ ## Keybindings Cheat Sheet
60
+
61
+ | Key | Action | Context |
62
+ | :--- | :--- | :--- |
63
+ | `[` / `Ctrl+B` | Toggle collapsible Workspace Sidebar | Global |
64
+ | `Tab` / `Shift+Tab` | Cycle focus across Sidebar, Canvas, and Comments Drawer | Global |
65
+ | `j` `k` / `↑` `↓` | Move across sidebar tree, page blocks, or database rows | Global |
66
+ | `Space` / `x` | Check/uncheck live `to_do` block or expand/collapse `toggle` block | Page Canvas |
67
+ | `w` / `f` / `y` | Toggle Centered vs Full Width / Favorite star / Copy code block | Page Canvas |
68
+ | `a` / `n` / `e` | Slash Quick Append (`/h1`, `/todo`, `/callout`) / New Page / `$EDITOR` | Page / Database |
69
+ | `C` | Toggle right-split Comments Peek Drawer & reply inline | Page Canvas |
70
+ | `1` / `2` / `3` | Switch Database views: **Table** / **Board (Kanban)** / **List** | Database |
71
+ | `f` / `s` / `m` | Filter rows / Cycle sort / Move Kanban card to another Status column | Database |
72
+ | `Ctrl+K` / `Ctrl+P` | Quick Find & Command Palette (FTS5 search + workspace commands) | Global |
73
+ | `u` / `Ctrl+F` / `v` | Link Extractor / File Picker (`z` zoxide) / HD Image Preview | Global |
74
+ | `Ctrl+S` / `Ctrl+,` / `?` | Switch Workspace / Settings & Palettes / Keyboard Shortcuts Help | Global |
75
+
76
+ ---
77
+
78
+ ## CLI, HTTP API & MCP
79
+
80
+ ### CLI (`--json` ready)
81
+
82
+ ```bash
83
+ # Search, read, append & export Notion pages
84
+ notion search "Q4 Roadmap" --json
85
+ notion pages list --json
86
+ notion pages get "Q4 Launch Plan"
87
+ notion pages get "Q4 Launch Plan" --json
88
+ notion pages get "Q4 Launch Plan" --json --full
89
+ notion pages edit "Q4 Launch Plan" --editor
90
+ notion pages append "Q4 Launch Plan" "/todo Tag v1.0 release"
91
+ notion pages export "Q4 Launch Plan" --out launch-plan.md
92
+ notion blocks edit <block-id> --text "Release **verified**" --json
93
+ notion blocks toggle <block-id>
94
+
95
+ # Query & create Notion database items, list workspace users
96
+ notion db list --json
97
+ notion db query "Q4 Roadmap" --json
98
+ notion db create-item "Q4 Roadmap" --title "Ship v1.0" --status "In Progress"
99
+ notion users list --json
100
+ notion comments list "Q4 Launch Plan" --json --limit 50 --cursor <next_cursor>
101
+ notion comments add "Q4 Launch Plan" "Green light for launch!"
102
+ notion download <url-or-block-id> --json
103
+
104
+ # Multi-workspace profiles & background sync daemon
105
+ notion workspaces list
106
+ notion workspaces add work --token ntn_...
107
+ notion workspaces use work
108
+ notion daemon start
109
+ ```
110
+
111
+ **Identifier resolution & `--json` exit contract:** UUIDs and Notion URLs pass through directly with zero extra lookups. Read commands accept exact or partial titles (preferring active pages), while write commands require a single exact title match among active pages (use `--unarchive` with a page ID or URL if an archived page is not in the local cache; pass a page ID or URL whenever duplicate or newly-created external titles may exist). Runtime failures under `--json` exit `1` and print `{"ok":false,"error":{"code":"...","message":"..."}}` to stdout (with `details.candidates` for ambiguous/missing titles); argument usage errors exit `2` with stderr usage text and empty stdout. On `--json`, treat exit `0` (and not `ok: false`) as success—some commands omit a top-level `ok` field, and `doctor --online --json` reports probe failures inside `online_probe.ok`.
112
+
113
+ ### Local HTTP JSON API (`notion serve`)
114
+
115
+ ```bash
116
+ notion serve --host 127.0.0.1 --port 8791 --api-key "$API_TOKEN"
117
+ curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8791/api/v1/search?q=Roadmap"
118
+ ```
119
+
120
+ Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
121
+
122
+ ### MCP Server (`notion mcp` — 20 Tools)
123
+
124
+ ```json
125
+ {
126
+ "mcpServers": {
127
+ "notion": {
128
+ "command": "notion",
129
+ "args": ["mcp"]
130
+ }
131
+ }
132
+ }
133
+ ```
134
+
135
+ Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
136
+
137
+ ---
138
+
139
+ ## `@bitefoundry` Enterprise Terminal Suite
140
+
141
+ | Package | Commands | Workspace | Interfaces |
142
+ | :--- | :--- | :--- | :--- |
143
+ | [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
144
+ | [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
145
+ | [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
146
+ | [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `bitefoundry-onedrive` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
147
+ | [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
148
+ | **`@bitefoundry/notion`** | `notion` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
149
+
150
+ ---
151
+
152
+ > **Disclaimer:** Unofficial terminal client for Notion. Not affiliated with, endorsed by, or sponsored by Notion Labs, Inc.
package/docs/API.md CHANGED
@@ -1,35 +1,37 @@
1
- # `@bitefoundry/notion` Local HTTP API Reference
2
-
3
- Start the local HTTP JSON API server (default `127.0.0.1:8791`):
4
-
5
- ```bash
6
- notion serve --port 8791
7
- # Optional API key protection (required when binding non-loopback hosts):
8
- notion serve --host 0.0.0.0 --port 8791 --api-key "$NOTION_LOCAL_API_KEY"
9
- ```
10
-
11
- When `--api-key` is configured, pass `x-api-key: <key>` or `Authorization: Bearer <key>` on all `/api/v1/*` routes.
12
-
13
- ## Endpoints
14
-
15
- | Method | Path | Description |
16
- |---|---|---|
17
- | `GET` | `/health` | Service health & version (`{ ok, service: "notion-cli", version }`) |
18
- | `GET` | `/api/v1/whoami` | Authenticated Notion bot/user and active workspace metadata |
19
- | `GET` | `/api/v1/workspaces` | List configured Notion workspace profiles |
20
- | `GET` | `/api/v1/search?q=<query>&remote=false&offline=false&limit=30` | Local SQLite FTS5 + Korean `<3` char LIKE search (or remote Notion search) |
21
- | `GET` | `/api/v1/pages?archived=false&refresh=false&offline=false` | List pages in active workspace |
22
- | `POST` | `/api/v1/pages` | Create a new page (`{ parent_id, title, icon?, markdown?, parent_is_database?, properties? }`) |
23
- | `GET` | `/api/v1/pages/{id}?offline=false` | Get full page detail (`detail` includes metadata, properties, block tree, comments, markdown, media refs, `incomplete_blocks`, and `comments_has_more`). Offline reads return HTTP 404 when the page body has not been fetched. |
24
- | `PATCH` | `/api/v1/pages/{id}` | Update page title, icon, properties, or archive/unarchive (`{ title?, icon?, archived?, properties? }`) |
25
- | `GET` | `/api/v1/pages/{id}/blocks?offline=false` | Get a page or block's recursive children. Offline reads return HTTP 404 for an uncached list and HTTP 200 for a verified empty list. |
26
- | `POST` | `/api/v1/pages/{id}/blocks` | Append Markdown or slash-style blocks (`{ markdown }`) |
27
- | `PATCH` | `/api/v1/blocks/{id}` | Update block text or toggle `to_do.checked` (`{ block_type?, text?, checked? }`) |
28
- | `GET` | `/api/v1/databases?refresh=false&offline=false` | List databases & schemas |
29
- | `POST` | `/api/v1/databases/{id}/query` | Query database rows (`{ filter?, sorts?, limit?, offline? }`). Returns HTTP 400 when `offline: true` is combined with `filter` or `sorts`. |
30
- | `POST` | `/api/v1/databases/{id}/items` | Create a new database item (`{ title, status?, properties?, body? }`) |
31
- | `GET` | `/api/v1/pages/{id}/comments?offline=false` | List page comments. Offline reads return HTTP 404 when comments have not been fetched or the last fetch failed. |
32
- | `POST` | `/api/v1/pages/{id}/comments` | Add a comment or discussion reply (`{ text, discussion_id? }`) |
33
- | `POST` | `/api/v1/sync` | Synchronize workspace pages & databases into SQLite WAL + FTS5 immediately (`{ ok, workspace_id, pages_count, databases_count, fetched_count, complete }`) |
34
-
35
- See [`docs/openapi.yaml`](openapi.yaml) for full schemas.
1
+ # `@bitefoundry/notion` Local HTTP API Reference
2
+
3
+ Start the local HTTP JSON API server (default `127.0.0.1:8791`):
4
+
5
+ ```bash
6
+ notion serve --port 8791
7
+ # Optional API key protection (required when binding non-loopback hosts):
8
+ notion serve --host 0.0.0.0 --port 8791 --api-key "$NOTION_LOCAL_API_KEY"
9
+ ```
10
+
11
+ When `--api-key` is configured, pass `x-api-key: <key>` or `Authorization: Bearer <key>` on all `/api/v1/*` routes.
12
+
13
+ Errors return `{ "ok": false, "error": "..." }` and preserve the upstream Notion API HTTP status code (such as `401`, `403`, `404`, `409`, or `429`) when a request fails upstream.
14
+
15
+ ## Endpoints
16
+
17
+ | Method | Path | Description |
18
+ |---|---|---|
19
+ | `GET` | `/health` | Service health & version (`{ ok, service: "notion-cli", version }`) |
20
+ | `GET` | `/api/v1/whoami` | Authenticated Notion bot/user and active workspace metadata |
21
+ | `GET` | `/api/v1/workspaces` | List configured Notion workspace profiles |
22
+ | `GET` | `/api/v1/search?q=<query>&remote=false&offline=false&limit=30` | Local SQLite FTS5 + Korean `<3` char LIKE search (or remote Notion search) |
23
+ | `GET` | `/api/v1/pages?archived=false&refresh=false&offline=false` | List pages in active workspace |
24
+ | `POST` | `/api/v1/pages` | Create a new page (`{ parent_id, title, icon?, markdown?, parent_is_database?, properties? }`) |
25
+ | `GET` | `/api/v1/pages/{id}?offline=false` | Get full page detail (`detail` includes metadata, properties, block tree, comments, markdown, media refs, `incomplete_blocks`, and `comments_has_more`). Offline reads return HTTP 404 when the page body has not been fetched. |
26
+ | `PATCH` | `/api/v1/pages/{id}` | Update page title, icon, properties, or archive/unarchive (`{ title?, icon?, archived?, properties? }`) |
27
+ | `GET` | `/api/v1/pages/{id}/blocks?offline=false` | Get a page or block's recursive children. Offline reads return HTTP 404 for an uncached list and HTTP 200 for a verified empty list. |
28
+ | `POST` | `/api/v1/pages/{id}/blocks` | Append Markdown or slash-style blocks (`{ markdown }`) |
29
+ | `PATCH` | `/api/v1/blocks/{id}` | Update block text or toggle `to_do.checked` (`{ block_type?, text?, checked? }`) |
30
+ | `GET` | `/api/v1/databases?refresh=false&offline=false` | List databases & schemas |
31
+ | `POST` | `/api/v1/databases/{id}/query` | Query database rows (`{ filter?, sorts?, limit?, offline? }`). Returns HTTP 400 when `offline: true` is combined with `filter` or `sorts`. |
32
+ | `POST` | `/api/v1/databases/{id}/items` | Create a new database item (`{ title, status?, properties?, body? }`) |
33
+ | `GET` | `/api/v1/pages/{id}/comments?offline=false` | List page comments. Offline reads return HTTP 404 when comments have not been fetched or the last fetch failed. |
34
+ | `POST` | `/api/v1/pages/{id}/comments` | Add a comment or discussion reply (`{ text, discussion_id? }`) |
35
+ | `POST` | `/api/v1/sync` | Synchronize workspace pages & databases into SQLite WAL + FTS5 immediately (`{ ok, workspace_id, pages_count, databases_count, fetched_count, complete }`) |
36
+
37
+ See [`docs/openapi.yaml`](openapi.yaml) for full schemas.