1# Notion Block Types Reference
2 
3This document provides comprehensive documentation for all supported block types in the Notion API.
4 
5## Block Structure
6 
7Every block contains these common fields:
8 
9```json
10{
11  "object": "block",
12  "id": "uuid",
13  "type": "block_type",
14  "parent": {"type": "page_id", "page_id": "..."},
15  "created_time": "2024-01-01T00:00:00.000Z",
16  "last_edited_time": "2024-01-01T00:00:00.000Z",
17  "created_by": {"object": "user", "id": "..."},
18  "last_edited_by": {"object": "user", "id": "..."},
19  "archived": false,
20  "in_trash": false,
21  "has_children": false,
22  "{type}": { /* type-specific properties */ }
23}
24```
25 
26## Text Blocks
27 
28### Paragraph
29 
30```json
31{
32  "type": "paragraph",
33  "paragraph": {
34    "rich_text": [{"type": "text", "text": {"content": "Paragraph text"}}],
35    "color": "default"
36  }
37}
38```
39 
40Supports children (nested blocks).
41 
42### Headings
43 
44```json
45{
46  "type": "heading_1",
47  "heading_1": {
48    "rich_text": [{"type": "text", "text": {"content": "Heading 1"}}],
49    "color": "default",
50    "is_toggleable": false
51  }
52}
53```
54 
55Types: `heading_1`, `heading_2`, `heading_3`
56 
57When `is_toggleable: true`, headings can contain children.
58 
59### Quote
60 
61```json
62{
63  "type": "quote",
64  "quote": {
65    "rich_text": [{"type": "text", "text": {"content": "Quote text"}}],
66    "color": "default"
67  }
68}
69```
70 
71Supports children.
72 
73### Callout
74 
75```json
76{
77  "type": "callout",
78  "callout": {
79    "rich_text": [{"type": "text", "text": {"content": "Callout text"}}],
80    "icon": {"type": "emoji", "emoji": "💡"},
81    "color": "gray_background"
82  }
83}
84```
85 
86Supports children. Icon can be emoji or file.
87 
88### Code
89 
90```json
91{
92  "type": "code",
93  "code": {
94    "rich_text": [{"type": "text", "text": {"content": "const x = 1;"}}],
95    "caption": [],
96    "language": "javascript"
97  }
98}
99```
100 
101Supported languages: `abap`, `arduino`, `bash`, `basic`, `c`, `clojure`, `coffeescript`, `cpp`, `csharp`, `css`, `dart`, `diff`, `docker`, `elixir`, `elm`, `erlang`, `flow`, `fortran`, `fsharp`, `gherkin`, `glsl`, `go`, `graphql`, `groovy`, `haskell`, `html`, `java`, `javascript`, `json`, `julia`, `kotlin`, `latex`, `less`, `lisp`, `livescript`, `lua`, `makefile`, `markdown`, `markup`, `matlab`, `mermaid`, `nix`, `objective-c`, `ocaml`, `pascal`, `perl`, `php`, `plain text`, `powershell`, `prolog`, `protobuf`, `python`, `r`, `reason`, `ruby`, `rust`, `sass`, `scala`, `scheme`, `scss`, `shell`, `sql`, `swift`, `typescript`, `vb.net`, `verilog`, `vhdl`, `visual basic`, `webassembly`, `xml`, `yaml`, `java/c/c++/c#`
102 
103### Equation
104 
105```json
106{
107  "type": "equation",
108  "equation": {
109    "expression": "E = mc^2"
110  }
111}
112```
113 
114Uses LaTeX/KaTeX syntax.
115 
116## List Blocks
117 
118### Bulleted List Item
119 
120```json
121{
122  "type": "bulleted_list_item",
123  "bulleted_list_item": {
124    "rich_text": [{"type": "text", "text": {"content": "List item"}}],
125    "color": "default"
126  }
127}
128```
129 
130Supports children (nested list items).
131 
132### Numbered List Item
133 
134```json
135{
136  "type": "numbered_list_item",
137  "numbered_list_item": {
138    "rich_text": [{"type": "text", "text": {"content": "List item"}}],
139    "color": "default"
140  }
141}
142```
143 
144Supports children.
145 
146### To-Do
147 
148```json
149{
150  "type": "to_do",
151  "to_do": {
152    "rich_text": [{"type": "text", "text": {"content": "Task"}}],
153    "checked": false,
154    "color": "default"
155  }
156}
157```
158 
159Supports children.
160 
161### Toggle
162 
163```json
164{
165  "type": "toggle",
166  "toggle": {
167    "rich_text": [{"type": "text", "text": {"content": "Toggle header"}}],
168    "color": "default"
169  }
170}
171```
172 
173Supports children (the toggle content).
174 
175## Media Blocks
176 
177### Image
178 
179```json
180{
181  "type": "image",
182  "image": {
183    "type": "external",
184    "external": {"url": "https://example.com/image.png"},
185    "caption": []
186  }
187}
188```
189 
190Or for uploaded files:
191 
192```json
193{
194  "type": "image",
195  "image": {
196    "type": "file",
197    "file": {"url": "https://...", "expiry_time": "..."},
198    "caption": []
199  }
200}
201```
202 
203Supported formats: `.bmp`, `.gif`, `.heic`, `.jpeg`, `.jpg`, `.png`, `.svg`, `.tif`, `.tiff`
204 
205### Video
206 
207```json
208{
209  "type": "video",
210  "video": {
211    "type": "external",
212    "external": {"url": "https://www.youtube.com/watch?v=..."},
213    "caption": []
214  }
215}
216```
217 
218Supported formats: `.mp4`, `.mov`, `.avi`, `.mkv`, `.wmv`, plus YouTube links
219 
220### Audio
221 
222```json
223{
224  "type": "audio",
225  "audio": {
226    "type": "external",
227    "external": {"url": "https://example.com/audio.mp3"},
228    "caption": []
229  }
230}
231```
232 
233Supported formats: `.mp3`, `.wav`, `.ogg`, `.oga`, `.m4a`
234 
235### File
236 
237```json
238{
239  "type": "file",
240  "file": {
241    "type": "external",
242    "external": {"url": "https://example.com/doc.pdf"},
243    "caption": [],
244    "name": "Document.pdf"
245  }
246}
247```
248 
249### PDF
250 
251```json
252{
253  "type": "pdf",
254  "pdf": {
255    "type": "external",
256    "external": {"url": "https://example.com/document.pdf"},
257    "caption": []
258  }
259}
260```
261 
262### Bookmark
263 
264```json
265{
266  "type": "bookmark",
267  "bookmark": {
268    "url": "https://example.com",
269    "caption": []
270  }
271}
272```
273 
274### Embed
275 
276```json
277{
278  "type": "embed",
279  "embed": {
280    "url": "https://example.com/embed",
281    "caption": []
282  }
283}
284```
285 
286**Note**: Embed rendering may differ from Notion app due to lack of iFramely integration.
287 
288### Link Preview
289 
290```json
291{
292  "type": "link_preview",
293  "link_preview": {
294    "url": "https://example.com"
295  }
296}
297```
298 
299**Read-only** - cannot be created via API.
300 
301## Structural Blocks
302 
303### Divider
304 
305```json
306{
307  "type": "divider",
308  "divider": {}
309}
310```
311 
312### Table of Contents
313 
314```json
315{
316  "type": "table_of_contents",
317  "table_of_contents": {
318    "color": "default"
319  }
320}
321```
322 
323### Breadcrumb
324 
325```json
326{
327  "type": "breadcrumb",
328  "breadcrumb": {}
329}
330```
331 
332### Column List and Column
333 
334```json
335{
336  "type": "column_list",
337  "column_list": {}
338}
339```
340 
341Column list contains column children:
342 
343```json
344{
345  "type": "column",
346  "column": {}
347}
348```
349 
350Columns contain actual content blocks. **Note**: Column list must have at least 2 columns.
351 
352### Table
353 
354```json
355{
356  "type": "table",
357  "table": {
358    "table_width": 3,
359    "has_column_header": true,
360    "has_row_header": false
361  }
362}
363```
364 
365Table contains `table_row` children:
366 
367```json
368{
369  "type": "table_row",
370  "table_row": {
371    "cells": [
372      [{"type": "text", "text": {"content": "Cell 1"}}],
373      [{"type": "text", "text": {"content": "Cell 2"}}],
374      [{"type": "text", "text": {"content": "Cell 3"}}]
375    ]
376  }
377}
378```
379 
380**Note**: `table_width` can only be set at creation, not updated later.
381 
382## Special Blocks
383 
384### Child Page
385 
386```json
387{
388  "type": "child_page",
389  "child_page": {
390    "title": "Page Title"
391  }
392}
393```
394 
395**Read-only** - use Create Page endpoint to create pages.
396 
397### Child Database
398 
399```json
400{
401  "type": "child_database",
402  "child_database": {
403    "title": "Database Title"
404  }
405}
406```
407 
408**Read-only** - use Create Database endpoint to create databases.
409 
410### Synced Block
411 
412Original synced block:
413 
414```json
415{
416  "type": "synced_block",
417  "synced_block": {
418    "synced_from": null
419  }
420}
421```
422 
423Reference to synced block:
424 
425```json
426{
427  "type": "synced_block",
428  "synced_block": {
429    "synced_from": {
430      "type": "block_id",
431      "block_id": "original-block-id"
432    }
433  }
434}
435```
436 
437**Note**: API doesn't support updating synced block content.
438 
439### Template (Deprecated)
440 
441```json
442{
443  "type": "template",
444  "template": {
445    "rich_text": [{"type": "text", "text": {"content": "Template button"}}]
446  }
447}
448```
449 
450**Deprecated** as of March 27, 2023 - use database templates instead.
451 
452### Unsupported
453 
454```json
455{
456  "type": "unsupported",
457  "unsupported": {}
458}
459```
460 
461Represents blocks not supported by the API.
462 
463## Color Options
464 
465Available colors for blocks that support the `color` property:
466 
467- `default`
468- `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`
469- `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background`
470 
471## Blocks That Support Children
472 
473The following block types can contain nested blocks:
474- `paragraph`
475- `bulleted_list_item`
476- `numbered_list_item`
477- `to_do`
478- `toggle`
479- `quote`
480- `callout`
481- `column_list` (contains `column` children)
482- `column` (contains content blocks)
483- `table` (contains `table_row` children)
484- `synced_block`
485- `template`
486- `heading_1`, `heading_2`, `heading_3` (when `is_toggleable: true`)
487- `child_page` (conceptually, via separate API calls)
488- `child_database` (conceptually, via separate API calls)
489