> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://notion.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server. # Append block children PATCH https://api.notion.com/v1/blocks/{block_id}/children Content-Type: application/json Creates and appends new children blocks to the parent `block_id` specified. Blocks can be parented by other blocks, pages, or databases. Returns a paginated list of newly created first level children [block objects](/reference/block). Existing blocks cannot be moved using this endpoint. Blocks are appended to the bottom of the parent block. To append a block in a specific place other than the bottom of the parent block, use the `"after"` parameter and set its value to the ID of the block that the new block should be appended after. 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. This 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](/reference/capabilities). ### 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](/reference/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](https://developers.notion.com/reference/status-codes#error-codes) of the Status codes documentation.* Reference: https://notion.ferndocs.com/reference/patch-block-children ## Request ### Path parameters - `block_id` (string, required) — Identifier for a [block](ref:block). Also accepts a [page](ref:page) ID. ### Headers - `Notion-Version` (string, required) — The [API version](/reference/versioning) to use for this request. The latest version is `<>`. ### Body (application/json) This endpoint expects an object. - `children` (list of any, required) — Child content to append to a container block as an array of [block objects](ref:block) - `after` (string, optional) — The ID of the existing block that the new block should be appended after. ## Response ### 200 200 - `object` (string, optional) - `results` (list of V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItems, optional) - `next_cursor` (any, optional) - `has_more` (boolean, optional, default: true) - `type` (string, optional) - `block` (V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaBlock, optional) ## Errors ### 400 Bad Request Error 400 ## Types ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItems - `object` (string, optional) - `id` (string, optional) - `parent` (V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsParent, optional) - `created_time` (string, optional) - `last_edited_time` (string, optional) - `created_by` (V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsCreatedBy, optional) - `last_edited_by` (V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsLastEditedBy, optional) - `has_children` (boolean, optional, default: true) - `archived` (boolean, optional, default: true) - `type` (string, optional) - `heading_2` (V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsHeading2, optional) ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaBlock ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsParent - `type` (string, optional) - `page_id` (string, optional) ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsCreatedBy - `object` (string, optional) - `id` (string, optional) ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsLastEditedBy - `object` (string, optional) - `id` (string, optional) ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsHeading2 - `rich_text` (list of V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsHeading2RichTextItems, optional) - `color` (string, optional) - `is_toggleable` (boolean, optional, default: true) ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsHeading2RichTextItems - `type` (string, optional) - `text` (V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsHeading2RichTextItemsText, optional) - `annotations` (V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsHeading2RichTextItemsAnnotations, optional) - `plain_text` (string, optional) - `href` (any, optional) ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsHeading2RichTextItemsText - `content` (string, optional) - `link` (any, optional) ### V1BlocksBlockIdChildrenPatchResponsesContentApplicationJsonSchemaResultsItemsHeading2RichTextItemsAnnotations - `bold` (boolean, optional, default: true) - `italic` (boolean, optional, default: true) - `strikethrough` (boolean, optional, default: true) - `underline` (boolean, optional, default: true) - `code` (boolean, optional, default: true) - `color` (string, optional) ## Examples **Request** ```json { "children": [ "string" ] } ``` **Response** ```json { "Result": { "value": "{\n\t\"object\": \"list\",\n\t\"results\": [\n\t\t{\n\t\t\t\"object\": \"block\",\n\t\t\t\"id\": \"c02fc1d3-db8b-45c5-a222-27595b15aea7\",\n\t\t\t\"parent\": {\n\t\t\t\t\"type\": \"page_id\",\n\t\t\t\t\"page_id\": \"59833787-2cf9-4fdf-8782-e53db20768a5\"\n\t\t\t},\n\t\t\t\"created_time\": \"2022-03-01T19:05:00.000Z\",\n\t\t\t\"last_edited_time\": \"2022-07-06T19:41:00.000Z\",\n\t\t\t\"created_by\": {\n\t\t\t\t\"object\": \"user\",\n\t\t\t\t\"id\": \"ee5f0f84-409a-440f-983a-a5315961c6e4\"\n\t\t\t},\n\t\t\t\"last_edited_by\": {\n\t\t\t\t\"object\": \"user\",\n\t\t\t\t\"id\": \"ee5f0f84-409a-440f-983a-a5315961c6e4\"\n\t\t\t},\n\t\t\t\"has_children\": false,\n\t\t\t\"archived\": false,\n\t\t\t\"type\": \"heading_2\",\n\t\t\t\"heading_2\": {\n\t\t\t\t\"rich_text\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"text\",\n\t\t\t\t\t\t\"text\": {\n\t\t\t\t\t\t\t\"content\": \"Lacinato kale\",\n\t\t\t\t\t\t\t\"link\": null\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"annotations\": {\n\t\t\t\t\t\t\t\"bold\": false,\n\t\t\t\t\t\t\t\"italic\": false,\n\t\t\t\t\t\t\t\"strikethrough\": false,\n\t\t\t\t\t\t\t\"underline\": false,\n\t\t\t\t\t\t\t\"code\": false,\n\t\t\t\t\t\t\t\"color\": \"default\"\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"plain_text\": \"Lacinato kale\",\n\t\t\t\t\t\t\"href\": null\n\t\t\t\t\t}\n\t\t\t\t],\n\t\t\t\t\"color\": \"default\",\n \"is_toggleable\": false\n\t\t\t}\n\t\t},\n\t\t{\n\t\t\t\"object\": \"block\",\n\t\t\t\"id\": \"acc7eb06-05cd-4603-a384-5e1e4f1f4e72\",\n\t\t\t\"parent\": {\n\t\t\t\t\"type\": \"page_id\",\n\t\t\t\t\"page_id\": \"59833787-2cf9-4fdf-8782-e53db20768a5\"\n\t\t\t},\n\t\t\t\"created_time\": \"2022-03-01T19:05:00.000Z\",\n\t\t\t\"last_edited_time\": \"2022-07-06T19:51:00.000Z\",\n\t\t\t\"created_by\": {\n\t\t\t\t\"object\": \"user\",\n\t\t\t\t\"id\": \"ee5f0f84-409a-440f-983a-a5315961c6e4\"\n\t\t\t},\n\t\t\t\"last_edited_by\": {\n\t\t\t\t\"object\": \"user\",\n\t\t\t\t\"id\": \"0c3e9826-b8f7-4f73-927d-2caaf86f1103\"\n\t\t\t},\n\t\t\t\"has_children\": false,\n\t\t\t\"archived\": false,\n\t\t\t\"type\": \"paragraph\",\n\t\t\t\"paragraph\": {\n\t\t\t\t\"rich_text\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"type\": \"text\",\n\t\t\t\t\t\t\"text\": {\n\t\t\t\t\t\t\t\"content\": \"Lacinato kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.\",\n\t\t\t\t\t\t\t\"link\": {\n\t\t\t\t\t\t\t\t\"url\": \"https://en.wikipedia.org/wiki/Lacinato_kale\"\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"annotations\": {\n\t\t\t\t\t\t\t\"bold\": false,\n\t\t\t\t\t\t\t\"italic\": false,\n\t\t\t\t\t\t\t\"strikethrough\": false,\n\t\t\t\t\t\t\t\"underline\": false,\n\t\t\t\t\t\t\t\"code\": false,\n\t\t\t\t\t\t\t\"color\": \"default\"\n\t\t\t\t\t\t},\n\t\t\t\t\t\t\"plain_text\": \"Lacinato kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.\",\n\t\t\t\t\t\t\"href\": \"https://en.wikipedia.org/wiki/Lacinato_kale\"\n\t\t\t\t\t}\n\t\t\t\t],\n\t\t\t\t\"color\": \"default\"\n\t\t\t}\n\t\t}\n\t],\n\t\"next_cursor\": null,\n\t\"has_more\": false,\n\t\"type\": \"block\",\n\t\"block\": {}\n}" } } ``` **SDK Code** ```javascript Notion SDK for JavaScript const { Client } = require('@notionhq/client'); const notion = new Client({ auth: process.env.NOTION_API_KEY }); (async () => { const blockId = 'b55c9c91-384d-452b-81db-d1ef79372b75'; const response = await notion.blocks.children.append({ block_id: blockId, children: [ { "heading_2": { "rich_text": [ { "text": { "content": "Lacinato kale" } } ] } }, { "paragraph": { "rich_text": [ { "text": { "content": "Lacinato kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.", "link": { "url": "https://en.wikipedia.org/wiki/Lacinato_kale" } } } ] } } ], }); console.log(response); })(); ``` ```python import requests url = "https://api.notion.com/v1/blocks/block_id/children" payload = { "children": ["string"] } headers = { "Notion-Version": "Notion-Version", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```go 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 \"string\"\n ]\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Notion-Version", "Notion-Version") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby 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["Content-Type"] = 'application/json' request.body = "{\n \"children\": [\n \"string\"\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.notion.com/v1/blocks/block_id/children") .header("Notion-Version", "Notion-Version") .header("Content-Type", "application/json") .body("{\n \"children\": [\n \"string\"\n ]\n}") .asString(); ``` ```php request('PATCH', 'https://api.notion.com/v1/blocks/block_id/children', [ 'body' => '{ "children": [ "string" ] }', 'headers' => [ 'Content-Type' => 'application/json', 'Notion-Version' => 'Notion-Version', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.notion.com/v1/blocks/block_id/children"); var request = new RestRequest(Method.PATCH); request.AddHeader("Notion-Version", "Notion-Version"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"children\": [\n \"string\"\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Notion-Version": "Notion-Version", "Content-Type": "application/json" ] let parameters = ["children": ["string"]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/blocks/block_id/children")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```