Summary
When an internal integration tries to create a workspace-root page, the Notion API returns a validation error that's technically accurate but not actionable for the typical CLI user. The CLI could detect this case up front (or improve the error wrap-around) and explain the standard workaround.
Repro
# With an internal integration token (the common case)
notion api POST /v1/pages --body '{
"parent": {"type": "workspace", "workspace": true},
"properties": {"title": [{"type":"text","text":{"content":"My Root Page"}}]}
}'Actual:
Error: validation_error: Provide a `parent.page_id` or `parent.database_id`
parameter to create a page, or use a public integration with `insert_content`
capability. Internal integrations aren't owned by a single user, so creating
workspace-level private pages is not supported.
Same thing happens if notion page create workspace --title X were ever attempted (though currently the CLI requires a parent id, which short-circuits this — but a user could reasonably expect it to work).
Expected
Two small improvements:
1. notion auth status / notion auth doctor should surface integration type, so the user can tell whether they have the "public integration with insert_content capability" or not:
$ notion auth status
Workspace: 付洋的备忘录
Bot: cli
Integration type: internal ← new line
Root-page create: not allowed for internal integrations
2. If a user hits this validation error via the CLI (now or in any future page create --parent workspace), wrap it with concrete next steps:
✗ Cannot create pages at workspace root.
This workspace is authenticated with an internal integration, which
Notion does not allow to create pages directly under the workspace.
Next steps:
• Create a parent page in the Notion UI, share it to this integration,
then pass its ID:
notion page create <shared-page-id> --title "My Root Page"
• To see what's already shared:
notion page list
• To switch to a public integration with `insert_content` capability,
see <link-to-notion-docs>.
Priority
Low — the API error message does eventually tell the user what's wrong, but reading through it takes a moment and the right workaround isn't immediately obvious to first-time CLI users.
Related
Discovered while trying to create a top-level "project notes" page from an agent workflow. Ended up creating the page under an existing shared top-level page instead, which is the correct pattern but wasn't obvious from the error alone.
Summary
When an internal integration tries to create a workspace-root page, the Notion API returns a validation error that's technically accurate but not actionable for the typical CLI user. The CLI could detect this case up front (or improve the error wrap-around) and explain the standard workaround.
Repro
Actual:
Same thing happens if
notion page create workspace --title Xwere ever attempted (though currently the CLI requires a parent id, which short-circuits this — but a user could reasonably expect it to work).Expected
Two small improvements:
1.
notion auth status/notion auth doctorshould surface integration type, so the user can tell whether they have the "public integration with insert_content capability" or not:2. If a user hits this validation error via the CLI (now or in any future
page create --parent workspace), wrap it with concrete next steps:Priority
Low — the API error message does eventually tell the user what's wrong, but reading through it takes a moment and the right workaround isn't immediately obvious to first-time CLI users.
Related
Discovered while trying to create a top-level "project notes" page from an agent workflow. Ended up creating the page under an existing shared top-level page instead, which is the correct pattern but wasn't obvious from the error alone.