fails with validation error () while works

[paoloanzn]

Summary

The notion pages markdown insert command appears to be broken in the current CLI build / API path.

In a real usage flow, insert fails with a validation-style error:

body.insert_content.content should be defined

Under the same environment and against the same target page, notion pages markdown replace succeeds and the content is written correctly.

This suggests the issue is likely in the CLI request body construction for the insert operation rather than workspace auth, page targeting, or markdown content itself.

Environment

• Repo: Gladium-AI/neo-notion-cli
• CLI version: v0.1.2
• Build commit: 534dc98
• CLI binary path: /home/paolo/.local/bin/notion
• Observed API version in docs/help: 2026-03-11
• OS: Linux amd64
• Runtime context where issue was observed: production-like real workflow writing to an existing Notion page

What I was trying to do

Populate an already-created Notion page body with markdown content.

The intended safe flow was:

1. verify the page exists
2. confirm current markdown/body state
3. use pages markdown insert to add content
4. verify by reading the page back

Actual behavior

pages markdown insert fails immediately with:

body.insert_content.content should be defined

Expected behavior

pages markdown insert should accept markdown content and append/insert it into the target page body successfully.

At minimum, if the input flag shape is wrong, the CLI should:

• map the provided content into the correct request field, or
• return a more actionable CLI-layer error before making the API call.

Strong indicator that this is specific to insert

Using the same page and same overall workflow:

• notion pages markdown insert ... -> fails
• notion pages markdown replace ... --allow-deleting-content -> succeeds
• reading the page back after replace confirms the content is present

So:

• auth was valid
• page ID was valid
• target page was writable
• markdown content itself was acceptable enough for the page write path

Likely root cause

The error message strongly suggests the CLI is sending a malformed or incomplete request body for the insert endpoint.

Specifically, it looks like the API expects something under a nested field like:

{
  "insert_content": {
    "content": "..."
  }
}

but the CLI may be doing one of the following instead:

• omitting insert_content.content
• mapping the CLI flag to the wrong JSON path
• using a stale request schema / old field name
• incorrectly serializing markdown insert payloads for the current API version

Reproduction notes

I observed this in a real page-write workflow rather than a synthetic isolated test, but the behavior should be straightforward to reproduce with:

1. create or locate an editable page
2. run a markdown insert command against it
3. observe the validation error
4. run markdown replace against the same page
5. observe successful write

Representative command shape used:

notion pages markdown insert --page-id <page-id> --new-str 'Some markdown content'

Representative successful comparison command:

notion pages markdown replace --page-id <page-id> --new-str 'Some markdown content' --allow-deleting-content

Why this matters

This is more than a cosmetic bug:

• insert is the safer operation for many agent and automation workflows
• replace is destructive by nature and requires stronger safeguards
• if users have to fall back to replace, they risk wiping page content accidentally
• this makes the CLI less reliable for incremental page editing, which is a common and important workflow

For agent-oriented usage specifically, this breaks the preferred safe mutation path:

• inspect -> insert/append -> verify

and forces a downgrade to:

• inspect -> replace -> verify

which is inherently riskier.

Suggested fix

Please inspect the implementation of pages markdown insert and compare it directly with the request builder for pages markdown replace.

Things worth checking:

1. Flag to request-body mapping
   • confirm --new-str (or equivalent input) is being mapped into the exact field expected by the insert endpoint
2. Current API schema alignment
   • verify the insert endpoint payload still matches the current Notion API version used by the CLI
3. Nil / empty content handling
   • ensure the CLI is not constructing an empty nested object or dropping content during normalization / request assembly
4. Parity tests
   • add tests that validate both insert and replace against expected outbound payloads
5. Error surfacing
   • if the payload cannot be built, emit a clearer CLI-side error than the downstream validation message

Suggested regression tests

A good regression suite would include:

1. Insert builds expected request body

Given:

notion pages markdown insert --page-id test-page --new-str 'Hello'

Assert that the outbound request contains the required nested content field expected by the API.

2. Insert and replace accept the same markdown input source

If replace works with --new-str, insert should support equivalent content input semantics unless explicitly documented otherwise.

3. Helpful error on empty content

If empty strings are disallowed, return a CLI validation error such as:

markdown insert content is empty

instead of sending an invalid body to the API.

Current workaround

Use:

notion pages markdown replace --page-id <page-id> --new-str '...' --allow-deleting-content

This works, but it is only a workaround and is not a safe substitute for insert in incremental-edit workflows.

Recommendation for docs until fixed

If this cannot be fixed immediately, it may be worth adding a temporary note in the README/help text that:

• pages markdown insert is currently unreliable / under investigation
• pages markdown replace is the current workaround
• users should exercise caution because replace is destructive

Additional note

The bug was discovered during a real Notion page population workflow where a page body had to be filled after creation. The page was initially empty, a minimal write was tested, and replace consistently succeeded while insert consistently failed. That pattern makes this look highly likely to be an endpoint-specific CLI bug rather than user error.