Append block children

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.blocks.children.append({
  block_id: "c02fc1d3-db8b-45c5-a222-27595b15aea7",
  children: [
    {
      type: "paragraph",
      paragraph: {
        rich_text: [{ text: { content: "Hello, world!" } }]
      }
    }
  ]
})

curl --request PATCH \
  --url https://api.notion.com/v1/blocks/{block_id}/children \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "children": [
    {
      "embed": {
        "url": "<string>",
        "caption": [
          {
            "text": {
              "content": "<string>",
              "link": {
                "url": "https://www.notion.com"
              }
            },
            "annotations": {
              "bold": true,
              "italic": true,
              "strikethrough": true,
              "underline": true,
              "code": true
            },
            "type": "text"
          }
        ]
      },
      "type": "embed",
      "object": "block"
    }
  ],
  "position": {
    "type": "after_block",
    "after_block": {
      "id": "<string>"
    }
  }
}
'

import requests

url = "https://api.notion.com/v1/blocks/{block_id}/children"

payload = {
    "children": [
        {
            "embed": {
                "url": "<string>",
                "caption": [
                    {
                        "text": {
                            "content": "<string>",
                            "link": { "url": "https://www.notion.com" }
                        },
                        "annotations": {
                            "bold": True,
                            "italic": True,
                            "strikethrough": True,
                            "underline": True,
                            "code": True
                        },
                        "type": "text"
                    }
                ]
            },
            "type": "embed",
            "object": "block"
        }
    ],
    "position": {
        "type": "after_block",
        "after_block": { "id": "<string>" }
    }
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/blocks/{block_id}/children",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'children' => [
        [
                'embed' => [
                                'url' => '<string>',
                                'caption' => [
                                                                [
                                                                                                                                'text' => [
                                                                                                                                                                                                                                                                'content' => '<string>',
                                                                                                                                                                                                                                                                'link' => [
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                'url' => 'https://www.notion.com'
                                                                                                                                                                                                                                                                ]
                                                                                                                                ],
                                                                                                                                'annotations' => [
                                                                                                                                                                                                                                                                'bold' => true,
                                                                                                                                                                                                                                                                'italic' => true,
                                                                                                                                                                                                                                                                'strikethrough' => true,
                                                                                                                                                                                                                                                                'underline' => true,
                                                                                                                                                                                                                                                                'code' => true
                                                                                                                                ],
                                                                                                                                'type' => 'text'
                                                                ]
                                ]
                ],
                'type' => 'embed',
                'object' => 'block'
        ]
    ],
    'position' => [
        'type' => 'after_block',
        'after_block' => [
                'id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/blocks/{block_id}/children"

	payload := strings.NewReader("{\n  \"children\": [\n    {\n      \"embed\": {\n        \"url\": \"<string>\",\n        \"caption\": [\n          {\n            \"text\": {\n              \"content\": \"<string>\",\n              \"link\": {\n                \"url\": \"https://www.notion.com\"\n              }\n            },\n            \"annotations\": {\n              \"bold\": true,\n              \"italic\": true,\n              \"strikethrough\": true,\n              \"underline\": true,\n              \"code\": true\n            },\n            \"type\": \"text\"\n          }\n        ]\n      },\n      \"type\": \"embed\",\n      \"object\": \"block\"\n    }\n  ],\n  \"position\": {\n    \"type\": \"after_block\",\n    \"after_block\": {\n      \"id\": \"<string>\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.notion.com/v1/blocks/{block_id}/children")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"children\": [\n    {\n      \"embed\": {\n        \"url\": \"<string>\",\n        \"caption\": [\n          {\n            \"text\": {\n              \"content\": \"<string>\",\n              \"link\": {\n                \"url\": \"https://www.notion.com\"\n              }\n            },\n            \"annotations\": {\n              \"bold\": true,\n              \"italic\": true,\n              \"strikethrough\": true,\n              \"underline\": true,\n              \"code\": true\n            },\n            \"type\": \"text\"\n          }\n        ]\n      },\n      \"type\": \"embed\",\n      \"object\": \"block\"\n    }\n  ],\n  \"position\": {\n    \"type\": \"after_block\",\n    \"after_block\": {\n      \"id\": \"<string>\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/blocks/{block_id}/children")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"children\": [\n    {\n      \"embed\": {\n        \"url\": \"<string>\",\n        \"caption\": [\n          {\n            \"text\": {\n              \"content\": \"<string>\",\n              \"link\": {\n                \"url\": \"https://www.notion.com\"\n              }\n            },\n            \"annotations\": {\n              \"bold\": true,\n              \"italic\": true,\n              \"strikethrough\": true,\n              \"underline\": true,\n              \"code\": true\n            },\n            \"type\": \"text\"\n          }\n        ]\n      },\n      \"type\": \"embed\",\n      \"object\": \"block\"\n    }\n  ],\n  \"position\": {\n    \"type\": \"after_block\",\n    \"after_block\": {\n      \"id\": \"<string>\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "type": "block",
  "block": {},
  "object": "list",
  "next_cursor": "<string>",
  "has_more": true,
  "results": [
    {
      "object": "block",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

PATCH

blocks

{block_id}

children

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.blocks.children.append({
  block_id: "c02fc1d3-db8b-45c5-a222-27595b15aea7",
  children: [
    {
      type: "paragraph",
      paragraph: {
        rich_text: [{ text: { content: "Hello, world!" } }]
      }
    }
  ]
})

curl --request PATCH \
  --url https://api.notion.com/v1/blocks/{block_id}/children \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "children": [
    {
      "embed": {
        "url": "<string>",
        "caption": [
          {
            "text": {
              "content": "<string>",
              "link": {
                "url": "https://www.notion.com"
              }
            },
            "annotations": {
              "bold": true,
              "italic": true,
              "strikethrough": true,
              "underline": true,
              "code": true
            },
            "type": "text"
          }
        ]
      },
      "type": "embed",
      "object": "block"
    }
  ],
  "position": {
    "type": "after_block",
    "after_block": {
      "id": "<string>"
    }
  }
}
'

import requests

url = "https://api.notion.com/v1/blocks/{block_id}/children"

payload = {
    "children": [
        {
            "embed": {
                "url": "<string>",
                "caption": [
                    {
                        "text": {
                            "content": "<string>",
                            "link": { "url": "https://www.notion.com" }
                        },
                        "annotations": {
                            "bold": True,
                            "italic": True,
                            "strikethrough": True,
                            "underline": True,
                            "code": True
                        },
                        "type": "text"
                    }
                ]
            },
            "type": "embed",
            "object": "block"
        }
    ],
    "position": {
        "type": "after_block",
        "after_block": { "id": "<string>" }
    }
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/blocks/{block_id}/children",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'children' => [
        [
                'embed' => [
                                'url' => '<string>',
                                'caption' => [
                                                                [
                                                                                                                                'text' => [
                                                                                                                                                                                                                                                                'content' => '<string>',
                                                                                                                                                                                                                                                                'link' => [
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                'url' => 'https://www.notion.com'
                                                                                                                                                                                                                                                                ]
                                                                                                                                ],
                                                                                                                                'annotations' => [
                                                                                                                                                                                                                                                                'bold' => true,
                                                                                                                                                                                                                                                                'italic' => true,
                                                                                                                                                                                                                                                                'strikethrough' => true,
                                                                                                                                                                                                                                                                'underline' => true,
                                                                                                                                                                                                                                                                'code' => true
                                                                                                                                ],
                                                                                                                                'type' => 'text'
                                                                ]
                                ]
                ],
                'type' => 'embed',
                'object' => 'block'
        ]
    ],
    'position' => [
        'type' => 'after_block',
        'after_block' => [
                'id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/blocks/{block_id}/children"

	payload := strings.NewReader("{\n  \"children\": [\n    {\n      \"embed\": {\n        \"url\": \"<string>\",\n        \"caption\": [\n          {\n            \"text\": {\n              \"content\": \"<string>\",\n              \"link\": {\n                \"url\": \"https://www.notion.com\"\n              }\n            },\n            \"annotations\": {\n              \"bold\": true,\n              \"italic\": true,\n              \"strikethrough\": true,\n              \"underline\": true,\n              \"code\": true\n            },\n            \"type\": \"text\"\n          }\n        ]\n      },\n      \"type\": \"embed\",\n      \"object\": \"block\"\n    }\n  ],\n  \"position\": {\n    \"type\": \"after_block\",\n    \"after_block\": {\n      \"id\": \"<string>\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.notion.com/v1/blocks/{block_id}/children")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"children\": [\n    {\n      \"embed\": {\n        \"url\": \"<string>\",\n        \"caption\": [\n          {\n            \"text\": {\n              \"content\": \"<string>\",\n              \"link\": {\n                \"url\": \"https://www.notion.com\"\n              }\n            },\n            \"annotations\": {\n              \"bold\": true,\n              \"italic\": true,\n              \"strikethrough\": true,\n              \"underline\": true,\n              \"code\": true\n            },\n            \"type\": \"text\"\n          }\n        ]\n      },\n      \"type\": \"embed\",\n      \"object\": \"block\"\n    }\n  ],\n  \"position\": {\n    \"type\": \"after_block\",\n    \"after_block\": {\n      \"id\": \"<string>\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/blocks/{block_id}/children")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"children\": [\n    {\n      \"embed\": {\n        \"url\": \"<string>\",\n        \"caption\": [\n          {\n            \"text\": {\n              \"content\": \"<string>\",\n              \"link\": {\n                \"url\": \"https://www.notion.com\"\n              }\n            },\n            \"annotations\": {\n              \"bold\": true,\n              \"italic\": true,\n              \"strikethrough\": true,\n              \"underline\": true,\n              \"code\": true\n            },\n            \"type\": \"text\"\n          }\n        ]\n      },\n      \"type\": \"embed\",\n      \"object\": \"block\"\n    }\n  ],\n  \"position\": {\n    \"type\": \"after_block\",\n    \"after_block\": {\n      \"id\": \"<string>\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "type": "block",
  "block": {},
  "object": "list",
  "next_cursor": "<string>",
  "has_more": true,
  "results": [
    {
      "object": "block",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

Returns a paginated list of newly created first level children block objects. Existing blocks cannot be moved using this endpoint. Once a block is appended as a child, it can’t be moved elsewhere via the API. For blocks that allow children, we allow up to two levels of nesting in a single request. There is a limit of 100 block children that can be appended by a single API request. Arrays of block children longer than 100 will result in an error.

Controlling insert position

By default, blocks are appended to the end of the parent block’s children. Use the position parameter to insert blocks at a specific location:

Position type	Description
`{ "type": "end" }`	Insert at the end of the parent’s children (default behavior)
`{ "type": "start" }`	Insert at the beginning of the parent’s children
`{ "type": "after_block", "after_block": { "id": "<block_id>" } }`	Insert after the specified block

{
  "children": [/* blocks */],
  "position": { "type": "start" }
}

{
  "children": [/* blocks */],
  "position": {
    "type": "after_block",
    "after_block": { "id": "12345678-1234-1234-1234-123456789abc" }
  }
}

Deprecated parameterThe after parameter is deprecated. Use the position parameter instead, which provides more flexibility including inserting at the start of the children list.If you’re currently using after, migrate to position with type after_block:

Before: { "children": [...], "after": "<block_id>" }
After: { "children": [...], "position": { "type": "after_block", "after_block": { "id": "<block_id>" } } }

You cannot specify both after and position in the same request.

Control notifications from page writes

Set notifications.mode to silent to skip the notifications Notion sends people about the change:

Page update notifications to people who get updates for the page through Notify me.
Notifications to people the content @mentions.
Notifications to people the change adds to a Person property.

Set it to default, or omit notifications, to use the standard behavior. Some effects of the change happen in either mode:

Database automations that the change triggers still run, including Send notification to actions.
Reminders set by the change still go off at their scheduled time.
Connection webhooks still receive events for the change.
Page history, page activity, and workspace audit logs still record the change.

Connection capabilitiesThis endpoint requires a connection to have insert content capabilities. Attempting to call this API without insert content capabilities will return an HTTP response with a 403 status code. For more information on connection capabilities, see the capabilities guide.

Errors

Returns a 404 HTTP response if the block specified by id doesn’t exist, or if the connection doesn’t have access to the block. Returns a 400 or 429 HTTP response if the request exceeds the request limits. Note: Each Public API endpoint can return several possible error codes. To see a full description of each type of error code, see the Error codes section of the Status codes documentation.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version

enum<string>

required

The API version to use for this request. The latest version is 2026-03-11.

Available options:

2026-03-11

Path Parameters

block_id

string

required

Body

application/json

children

required

Maximum array length: 100

Show child attributes

position

object

Option 1
Option 2
Option 3

Show child attributes

notifications

object

Controls the notifications Notion sends people about this change. Set mode to "silent" to skip page update notifications, @mention notifications, and notifications to people added to a Person property, or "default" to use the standard behavior. Database automations, reminders, and connection webhooks still work as usual. Page history, page activity, and workspace audit logs still record the change.

Show child attributes

Response

type

string

required

Allowed value: "block"

block

object

required

object

string

required

Allowed value: "list"

next_cursor

string | null

required

has_more

boolean

required

results

required

Show child attributes

Notion API

Objects

Endpoints

Webhook events

Append block children

Controlling insert position

Control notifications from page writes

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Controlling insert position

​Control notifications from page writes

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Controlling insert position

Control notifications from page writes

Errors