Skip to contents

R6 Class for Blocks children endpoint

Source: R/endpoints.R
BlocksChildrenEndpoint.Rd

Handle all block children operations in the Notion API

Note: Access this endpoint through the client instance, e.g., notion$blocks$children. Not to be instantiated directly.

Value

A list containing the parsed API response.

Methods

Public methods

Method new()

Initialise block children endpoint. Not to be called directly, e.g., use notion$pages$children instead.

Usage

BlocksChildrenEndpoint$new(client)

Arguments

client

Notion Client instance

Method retrieve()

Retrieve a block's children

Usage

BlocksChildrenEndpoint$retrieve(block_id, start_cursor = NULL, page_size = 100)

Arguments

block_id

String (required). The ID for a Notion block.

start_cursor

Character. For pagination. If provided, returns results starting from this cursor. If NULL, returns the first page of results.

page_size

Integer. Number of items to return per page (1-100). Defaults to 100.

Details

Endpoint documentation

Method append()

Append block children

Usage

BlocksChildrenEndpoint$append(block_id, children, after = NULL)

Arguments

block_id

String (required). The ID for a Notion block.

children

List of lists (JSON array) (required). Block objects to append as children to the block.

after

Character. The ID of the existing block after which the new children are appended.

Details

Endpoint documentation

Examples

notion <- notion_client()

# ----- append children to a block
notion$blocks$children$append(
  block_id = "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba",
  children = list(
    # add a level 2 heading called "Test Heading"
    list(
      object = "block",
      heading_2 = list(
        rich_text = list(list(
          text = list(content = "Test Heading")
        ))
      )
    )
  )
)
#> {
#>   "object": "list",
#>   "results": [
#>     {
#>       "object": "block",
#>       "id": "23933ea0-c1e4-81dc-9f56-f3fa251a757f",
#>       "parent": {
#>         "type": "page_id",
#>         "page_id": "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba"
#>       },
#>       "created_time": "2025-07-23T05:00:00.000Z",
#>       "last_edited_time": "2025-07-23T05:00:00.000Z",
#>       "created_by": {
#>         "object": "user",
#>         "id": "6b786605-e456-4237-9c61-5efaff23c081"
#>       },
#>       "last_edited_by": {
#>         "object": "user",
#>         "id": "6b786605-e456-4237-9c61-5efaff23c081"
#>       },
#>       "has_children": false,
#>       "archived": false,
#>       "in_trash": false,
#>       "type": "heading_2",
#>       "heading_2": {
#>         "rich_text": [
#>           {
#>             "type": "text",
#>             "text": {
#>               "content": "Test Heading",
#>               "link": {}
#>             },
#>             "annotations": {
#>               "bold": false,
#>               "italic": false,
#>               "strikethrough": false,
#>               "underline": false,
#>               "code": false,
#>               "color": "default"
#>             },
#>             "plain_text": "Test Heading",
#>             "href": {}
#>           }
#>         ],
#>         "is_toggleable": false,
#>         "color": "default"
#>       }
#>     }
#>   ],
#>   "next_cursor": {},
#>   "has_more": false,
#>   "type": "block",
#>   "block": {},
#>   "request_id": "9e6e8dcd-dac3-479f-9d0c-b5ef44b628c9"
#> } 

# ----- retrieve children of a block
notion$blocks$children$retrieve("23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba")
#> {
#>   "object": "list",
#>   "results": [
#>     {
#>       "object": "block",
#>       "id": "23933ea0-c1e4-81dc-9f56-f3fa251a757f",
#>       "parent": {
#>         "type": "page_id",
#>         "page_id": "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba"
#>       },
#>       "created_time": "2025-07-23T05:00:00.000Z",
#>       "last_edited_time": "2025-07-23T05:00:00.000Z",
#>       "created_by": {
#>         "object": "user",
#>         "id": "6b786605-e456-4237-9c61-5efaff23c081"
#>       },
#>       "last_edited_by": {
#>         "object": "user",
#>         "id": "6b786605-e456-4237-9c61-5efaff23c081"
#>       },
#>       "has_children": false,
#>       "archived": false,
#>       "in_trash": false,
#>       "type": "heading_2",
#>       "heading_2": {
#>         "rich_text": [
#>           {
#>             "type": "text",
#>             "text": {
#>               "content": "Test Heading",
#>               "link": {}
#>             },
#>             "annotations": {
#>               "bold": false,
#>               "italic": false,
#>               "strikethrough": false,
#>               "underline": false,
#>               "code": false,
#>               "color": "default"
#>             },
#>             "plain_text": "Test Heading",
#>             "href": {}
#>           }
#>         ],
#>         "is_toggleable": false,
#>         "color": "default"
#>       }
#>     }
#>   ],
#>   "next_cursor": {},
#>   "has_more": false,
#>   "type": "block",
#>   "block": {},
#>   "request_id": "c6a86d45-a6ea-4d08-87e5-6c47192c3495"
#> } 

# ----- iterate through paginated results
if (FALSE) { # \dontrun{
start_cursor <- NULL
has_more <- FALSE
resps <- list()
i <- 1

while (has_more) {
  resps[[i]] <- notion$blocks$children$retrieve(
    "2926b407e3c44b49a1830609abe6744f",
    start_cursor
  )
  has_more <- resps[[i]][["has_more"]]
  start_cursor <- resps[[i]][["next_cursor"]]
  i <- i + 1
}
} # }