> 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. # Update a block PATCH https://api.notion.com/v1/blocks/{block_id} Content-Type: application/json Updates the content for the specified `block_id` based on the block type. Supported fields based on the block object type (see [Block object](/reference/block#block-type-object) for available fields and the expected input for each field). **Note**: The update replaces the *entire* value for a given field. If a field is omitted (ex: omitting `checked` when updating a `to_do` block), the value will not be changed. To update `child_page` type blocks, use the [Update page](/reference/patch-page) endpoint. Updating the page's `title` updates the text displayed in the associated `child_page` block. To update `child_database` type blocks, use the [Update database](/reference/update-a-database) endpoint. Updating the page's `title` updates the text displayed in the associated `child_database` block. A block's children *CANNOT* be directly updated with this endpoint. Instead use [Append block children](/reference/patch-block-children) to add children. To update the toggle of a `heading` block, you can include the optional `is_toggleable` property in the request. Toggle can be added and removed from a `heading` block. However, you cannot remove toggle from a `heading` block if it has children. All children *MUST* be removed before revoking toggle from a `heading` block. ### Success Returns a 200 HTTP response containing the updated [block object](/reference/block) on success. This endpoint requires an integration to have update content capabilities. Attempting to call this API without update 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 doesn't exist, has been archived, or if the integration doesn't have access to the page. Returns a 400 if the `type` for the block is incorrect or the input is incorrect for a given field. Returns a 400 or a 429 HTTP response if the request exceeds the [request limits](/reference/request-limits). *Note: Each Public API endpoint can return several possible error codes. See the [Error codes section](https://developers.notion.com/reference/status-codes#error-codes) of the Status codes documentation for more information.* Reference: https://notion.ferndocs.com/reference/update-a-block ## Request ### Path parameters - `block_id` (string, required) — Identifier for a Notion block ### 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. - `{type}` (V1BlocksBlockIdPatchRequestBodyContentApplicationJsonSchemaType, optional) — The [block object `type`](ref:block#block-object-keys) value with the properties to be updated. Currently only `text` (for supported block types) and `checked` (for `to_do` blocks) fields can be updated. - `archived` (boolean, optional, default: true) — Set to true to archive (delete) a block. Set to false to un-archive (restore) a block. ## Response ### 200 200 - `object` (string, optional) - `id` (string, optional) - `parent` (V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaParent, optional) - `created_time` (string, optional) - `last_edited_time` (string, optional) - `created_by` (V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaCreatedBy, optional) - `last_edited_by` (V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaLastEditedBy, optional) - `has_children` (boolean, optional, default: true) - `archived` (boolean, optional, default: true) - `type` (string, optional) - `heading_2` (V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaHeading2, optional) ## Errors ### 400 Bad Request Error 400 ## Types ### V1BlocksBlockIdPatchRequestBodyContentApplicationJsonSchemaType The [block object `type`](ref:block#block-object-keys) value with the properties to be updated. Currently only `text` (for supported block types) and `checked` (for `to_do` blocks) fields can be updated. ### V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaParent - `type` (string, optional) - `page_id` (string, optional) ### V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaCreatedBy - `object` (string, optional) - `id` (string, optional) ### V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaLastEditedBy - `object` (string, optional) - `id` (string, optional) ### V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaHeading2 - `rich_text` (list of V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaHeading2RichTextItems, optional) - `color` (string, optional) - `is_toggleable` (boolean, optional, default: true) ### V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaHeading2RichTextItems - `type` (string, optional) - `text` (V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaHeading2RichTextItemsText, optional) - `annotations` (V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaHeading2RichTextItemsAnnotations, optional) - `plain_text` (string, optional) - `href` (any, optional) ### V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaHeading2RichTextItemsText - `content` (string, optional) - `link` (any, optional) ### V1BlocksBlockIdPatchResponsesContentApplicationJsonSchemaHeading2RichTextItemsAnnotations - `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 {} ``` **Response** ```json { "Result": { "value": "{\n\t\"object\": \"block\",\n\t\"id\": \"c02fc1d3-db8b-45c5-a222-27595b15aea7\",\n\t\"parent\": {\n\t\t\"type\": \"page_id\",\n\t\t\"page_id\": \"59833787-2cf9-4fdf-8782-e53db20768a5\"\n\t},\n\t\"created_time\": \"2022-03-01T19:05:00.000Z\",\n\t\"last_edited_time\": \"2022-07-06T19:41:00.000Z\",\n\t\"created_by\": {\n\t\t\"object\": \"user\",\n\t\t\"id\": \"ee5f0f84-409a-440f-983a-a5315961c6e4\"\n\t},\n\t\"last_edited_by\": {\n\t\t\"object\": \"user\",\n\t\t\"id\": \"ee5f0f84-409a-440f-983a-a5315961c6e4\"\n\t},\n\t\"has_children\": false,\n\t\"archived\": false,\n\t\"type\": \"heading_2\",\n\t\"heading_2\": {\n\t\t\"rich_text\": [\n\t\t\t{\n\t\t\t\t\"type\": \"text\",\n\t\t\t\t\"text\": {\n\t\t\t\t\t\"content\": \"Lacinato kale\",\n\t\t\t\t\t\"link\": null\n\t\t\t\t},\n\t\t\t\t\"annotations\": {\n\t\t\t\t\t\"bold\": false,\n\t\t\t\t\t\"italic\": false,\n\t\t\t\t\t\"strikethrough\": false,\n\t\t\t\t\t\"underline\": false,\n\t\t\t\t\t\"code\": false,\n\t\t\t\t\t\"color\": \"green\"\n\t\t\t\t},\n\t\t\t\t\"plain_text\": \"Lacinato kale\",\n\t\t\t\t\"href\": null\n\t\t\t}\n\t\t],\n\t\t\"color\": \"default\",\n \"is_toggleable\": false\n\t}\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 = '9bc30ad4-9373-46a5-84ab-0a7845ee52e6'; const response = await notion.blocks.update({ "block_id": blockId, "heading_2": { "rich_text": [ { "text": { "content": "Lacinato kale" }, "annotations": { "color": "green" } } ] } }); console.log(response); })(); ``` ```python import requests url = "https://api.notion.com/v1/blocks/block_id" payload = {} 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" payload := strings.NewReader("{}") 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") 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 = "{}" 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") .header("Notion-Version", "Notion-Version") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('PATCH', 'https://api.notion.com/v1/blocks/block_id', [ 'body' => '{}', '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"); var request = new RestRequest(Method.PATCH); request.AddHeader("Notion-Version", "Notion-Version"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Notion-Version": "Notion-Version", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/blocks/block_id")! 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() ```