Write page content

There are three ways to write a document’s content. They all save to the same document, and you can mix them.

Way	Best for	Endpoints
Blocks	Adding or changing specific blocks by ID	Append, update, delete
Markdown	Writing or editing a document as text	Create a page, Update with Markdown
Templates	Starting from a layout your team made in the app	List templates, Create a page

An integration needs a capability for each: Insert content to add, and Update content to change or delete. Markdown edits only need Update content. See Capabilities.

Add a document

A row goes in a database, and a subpage goes under a document.

curl https://api.bottari.ai/v1/pages \
  -X POST \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": { "data_source_id": "exampleDb001" },
    "markdown": "# Launch checklist\n\n- [ ] Update the changelog"
  }'

Add and change blocks

Add blocks to the end of the document. The response includes the new blocks and their IDs.

curl https://api.bottari.ai/v1/blocks/exampleRow01/children \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      { "heading_2": { "rich_text": [{ "text": { "content": "Results" } }] } }
    ]
  }'

Then change one by ID. Only the fields you send change.

curl https://api.bottari.ai/v1/blocks/exampleRow01.exampleBlk01 \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{ "to_do": { "checked": true } }'

Edit as text

Read the document, then replace a piece of text.

curl https://api.bottari.ai/v1/pages/exampleRow01/markdown \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "update_content",
    "update_content": {
      "content_updates": [
        { "old_str": "Update the changelog", "new_str": "Publish the changelog" }
      ]
    }
  }'

When people are editing

Writes go into the live document, so people with it open see them right away.

A block write only touches that block’s lines, and text people are typing elsewhere stays.
update_content works the same way. It only touches the lines it changes.
replace_content has no version check. It overwrites what was typed after you read the document.
If someone is typing on the line you change, their cursor can move to the next line when the write changes what holds it, such as adding the first indented child to a paragraph.

A write you get a 200 for is saved. A 503 means the save couldn’t be confirmed, and the write may already show for people who have the document open. Before sending an append again, read the document, so blocks aren’t added twice.

When requests overlap

Applying a template to a document that’s already applying one returns 409 conflict_error. Nothing is written. Send the request again. Other writes to the same document at the same time are saved one after another.

Undo a delete

Deleted blocks stay in the trash for 30 days, and you can restore them. This includes blocks removed by Markdown edits and erase_content. See Delete a block.

Mentions

Mentioning a person in new content notifies them. To skip this, send notifications: { "mode": "silent" } with Append block children, Create a page, or Update a page. Updating a block and Markdown edits always notify. The notification doesn’t name your integration. It says someone mentioned them.

Webhooks

Your own writes send page.content_updated events too. To avoid a loop, skip events written only by your bot. See Authors.

Get started

Import data

Authentication and access

Write content

Limits

Webhooks

Add a document

Add and change blocks

Edit as text

When people are editing

When requests overlap

Undo a delete

Mentions

Webhooks

​Add a document

​Add and change blocks

​Edit as text

​When people are editing

​When requests overlap

​Undo a delete

​Mentions

​Webhooks

Add a document

Add and change blocks

Edit as text

When people are editing

When requests overlap

Undo a delete

Mentions

Webhooks