Skip to main content
PATCH
/
v1
/
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!" } }]
      }
    }
  ]
})
{
  "type": "block",
  "block": {},
  "object": "list",
  "next_cursor": "<string>",
  "has_more": true,
  "results": [
    {
      "object": "block",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}
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 typeDescription
{ "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" }
}
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.
Integration capabilitiesThis endpoint requires an integration 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 integration capabilities, see the capabilities guide.

​
Errors

Returns a 404 HTTP response if the block specified by id doesn’t exist, or if the integration 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 2025-09-03.

Available options:
2025-09-03

Path Parameters

​
block_id
string
required

Body

application/json
​
children
(Embed · object | Bookmark · object | Image · object | Video · object | Pdf · object | File · object | Audio · object | Code · object | Equation · object | Divider · object | Breadcrumb · object | Table Of Contents · object | Link To Page · object | Table Row · object | Table · object | Column List · object | Column · object | Heading 1 · object | Heading 2 · object | Heading 3 · object | Paragraph · object | Bulleted List Item · object | Numbered List Item · object | Quote · object | To Do · object | Toggle · object | Template · object | Callout · object | Synced Block · object)[]
required
Maximum array length: 100
​
after
string
​
position
object

Response

​
type
enum<string>
required
Available options:
block
​
block
object
required
​
object
enum<string>
required
Available options:
list
​
next_cursor
string | null
required
​
has_more
boolean
required
​
results
(object | Paragraph · object | Heading 1 · object | Heading 2 · object | Heading 3 · object | Bulleted List Item · object | Numbered List Item · object | Quote · object | To Do · object | Toggle · object | Template · object | Synced Block · object | Child Page · object | Child Database · object | Equation · object | Code · object | Callout · object | Divider · object | Breadcrumb · object | Table Of Contents · object | Column List · object | Column · object | Link To Page · object | Table · object | Table Row · object | Embed · object | Bookmark · object | Image · object | Video · object | Pdf · object | File · object | Audio · object | Link Preview · object | Unsupported · object)[]
required