> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bottari.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Write page content

> Choose between blocks, Markdown, and templates, and see how writes work alongside people editing.

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](https://developers.bottari.ai/api-reference/blocks/append.md), [update](https://developers.bottari.ai/api-reference/blocks/update.md), [delete](https://developers.bottari.ai/api-reference/blocks/delete.md) |
| Markdown | Writing or editing a document as text | [Create a page](https://developers.bottari.ai/api-reference/pages/create.md), [Update with Markdown](https://developers.bottari.ai/api-reference/pages/update-markdown.md) |
| Templates | Starting from a layout your team made in the app | [List templates](https://developers.bottari.ai/api-reference/data-sources/templates.md), [Create a page](https://developers.bottari.ai/api-reference/pages/create.md#templates) |

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](https://developers.bottari.ai/auth/capabilities.md).

## Add a document

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

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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](https://developers.bottari.ai/api-reference/blocks/delete.md).

## Mentions

Mentioning a person in new content notifies them. To skip this, send `notifications: { "mode": "silent" }` with [Append block children](https://developers.bottari.ai/api-reference/blocks/append.md), [Create a page](https://developers.bottari.ai/api-reference/pages/create.md), or [Update a page](https://developers.bottari.ai/api-reference/pages/update.md). 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](https://developers.bottari.ai/webhooks/events.md#authors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.