Append Block Children

Use Case

Use this endpoint to append new direct children under a block. You can optionally insert them before or after an existing child block.

Endpoint

Permissions

Requires blocks.write and write access to the parent block.

Parameters

Request Example

{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "Follow-up notes"
            }
          }
        ]
      }
    },
    {
      "object": "block",
      "type": "to_do",
      "to_do": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "Confirm launch date"
            }
          }
        ],
        "checked": false,
        "color": "default"
      }
    }
  ],
  "after": null
}

To insert before an existing direct child block, pass before instead:

{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "Notes inserted before the target block"
            }
          }
        ]
      }
    }
  ],
  "before": "12121212-1212-4212-8212-121212121212"
}

Response Example

{
  "object": "list",
  "results": [
    {
      "object": "block",
      "id": "44444444-4444-4444-8444-444444444444",
      "parent": {
        "type": "page_id",
        "page_id": "11111111-1111-4111-8111-111111111111"
      },
      "created_time": "2026-04-09T08:00:00.000Z",
      "last_edited_time": "2026-04-09T09:30:00.000Z",
      "created_by": {
        "object": "user",
        "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
      },
      "last_edited_by": {
        "object": "user",
        "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
      },
      "has_children": false,
      "in_trash": false,
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "Project kickoff notes",
              "link": null
            },
            "plain_text": "Project kickoff notes",
            "href": null
          }
        ],
        "color": "default"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Behavior

• children is required and can contain up to 100 top-level blocks.
• Only writable block types are accepted.
• Nested child blocks are supported for the block types that can contain children, within the supported depth limit.
• If neither after nor before is provided, new children are appended to the end of the parent block.
• If after is provided, it must refer to an existing direct child of the parent block, and new children are inserted after it.
• If before is provided, it must refer to an existing direct child of the parent block, and new children are inserted before it.
• after and before are mutually exclusive. If both are provided, the request returns 400 validation_error.
• When multiple children are provided, their array order is preserved at the insertion point.

Errors

• 400 validation_error: invalid children, both after and before are provided, or the after / before value is not a direct child of the parent block.
• 400 unsupported_block_type: child block type cannot be written.
• 401 unauthorized: invalid or expired token.
• 403 forbidden: missing blocks.write or no access.
• 404 not_found: parent block does not exist.

Related Docs

Prerequisites

• Get Block Children

Next Steps

• Get Block
• Markdown Read

References

• Block Types