notion-blocks-api-research.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Notion Block API - Complete Research Document",
  "description": "Comprehensive research of all Notion API block types, properties, and enums extracted from official documentation (developers.notion.com/reference/block)",

  "definitions": {

    "uuid": {
      "type": "string",
      "format": "uuid",
      "description": "UUIDv4 identifier"
    },

    "iso8601_datetime": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 formatted datetime string"
    },

    "color": {
      "type": "string",
      "enum": [
        "blue",
        "blue_background",
        "brown",
        "brown_background",
        "default",
        "gray",
        "gray_background",
        "green",
        "green_background",
        "orange",
        "orange_background",
        "pink",
        "pink_background",
        "purple",
        "purple_background",
        "red",
        "red_background",
        "yellow",
        "yellow_background"
      ]
    },

    "code_language": {
      "type": "string",
      "enum": [
        "abap",
        "arduino",
        "bash",
        "basic",
        "c",
        "clojure",
        "coffeescript",
        "c++",
        "c#",
        "css",
        "dart",
        "diff",
        "docker",
        "elixir",
        "elm",
        "erlang",
        "flow",
        "fortran",
        "f#",
        "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#"
      ]
    },

    "block_type": {
      "type": "string",
      "enum": [
        "bookmark",
        "breadcrumb",
        "bulleted_list_item",
        "callout",
        "child_database",
        "child_page",
        "code",
        "column",
        "column_list",
        "divider",
        "embed",
        "equation",
        "file",
        "heading_1",
        "heading_2",
        "heading_3",
        "image",
        "link_preview",
        "link_to_page",
        "meeting_notes",
        "numbered_list_item",
        "paragraph",
        "pdf",
        "quote",
        "synced_block",
        "table",
        "table_of_contents",
        "table_row",
        "template",
        "to_do",
        "toggle",
        "audio",
        "video",
        "unsupported"
      ]
    },

    "list_format": {
      "type": "string",
      "enum": ["numbers", "letters", "roman"]
    },

    "meeting_notes_status": {
      "type": "string",
      "enum": [
        "transcription_not_started",
        "transcription_paused",
        "transcription_in_progress",
        "summary_in_progress",
        "notes_ready"
      ]
    },

    "partial_user": {
      "type": "object",
      "properties": {
        "object": { "type": "string", "const": "user" },
        "id": { "$ref": "#/definitions/uuid" }
      },
      "required": ["object", "id"]
    },

    "parent": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["page_id", "block_id", "database_id", "workspace"]
        },
        "page_id": { "$ref": "#/definitions/uuid" },
        "block_id": { "$ref": "#/definitions/uuid" },
        "database_id": { "$ref": "#/definitions/uuid" }
      },
      "required": ["type"]
    },

    "link_object": {
      "type": ["object", "null"],
      "properties": {
        "url": { "type": "string", "format": "uri" }
      },
      "required": ["url"]
    },

    "annotations": {
      "type": "object",
      "properties": {
        "bold": { "type": "boolean" },
        "italic": { "type": "boolean" },
        "strikethrough": { "type": "boolean" },
        "underline": { "type": "boolean" },
        "code": { "type": "boolean" },
        "color": { "$ref": "#/definitions/color" }
      },
      "required": ["bold", "italic", "strikethrough", "underline", "code", "color"]
    },

    "rich_text_text": {
      "type": "object",
      "description": "Rich text object of type 'text'",
      "properties": {
        "type": { "type": "string", "const": "text" },
        "text": {
          "type": "object",
          "properties": {
            "content": { "type": "string" },
            "link": { "$ref": "#/definitions/link_object" }
          },
          "required": ["content", "link"]
        },
        "annotations": { "$ref": "#/definitions/annotations" },
        "plain_text": { "type": "string" },
        "href": { "type": ["string", "null"] }
      },
      "required": ["type", "text", "annotations", "plain_text", "href"]
    },

    "mention_database": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "database" },
        "database": {
          "type": "object",
          "properties": {
            "id": { "$ref": "#/definitions/uuid" }
          },
          "required": ["id"]
        }
      },
      "required": ["type", "database"]
    },

    "mention_date": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "date" },
        "date": {
          "type": "object",
          "properties": {
            "start": { "type": "string" },
            "end": { "type": ["string", "null"] }
          },
          "required": ["start", "end"]
        }
      },
      "required": ["type", "date"]
    },

    "mention_link_preview": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "link_preview" },
        "link_preview": {
          "type": "object",
          "properties": {
            "url": { "type": "string", "format": "uri" }
          },
          "required": ["url"]
        }
      },
      "required": ["type", "link_preview"]
    },

    "mention_page": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "page" },
        "page": {
          "type": "object",
          "properties": {
            "id": { "$ref": "#/definitions/uuid" }
          },
          "required": ["id"]
        }
      },
      "required": ["type", "page"]
    },

    "mention_template_mention": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "template_mention" },
        "template_mention": {
          "type": "object",
          "oneOf": [
            {
              "properties": {
                "type": { "type": "string", "const": "template_mention_date" },
                "template_mention_date": {
                  "type": "string",
                  "enum": ["today", "now"]
                }
              },
              "required": ["type", "template_mention_date"]
            },
            {
              "properties": {
                "type": { "type": "string", "const": "template_mention_user" },
                "template_mention_user": {
                  "type": "string",
                  "enum": ["me"]
                }
              },
              "required": ["type", "template_mention_user"]
            }
          ]
        }
      },
      "required": ["type", "template_mention"]
    },

    "mention_user": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "user" },
        "user": { "$ref": "#/definitions/partial_user" }
      },
      "required": ["type", "user"]
    },

    "mention_object": {
      "type": "object",
      "oneOf": [
        { "$ref": "#/definitions/mention_database" },
        { "$ref": "#/definitions/mention_date" },
        { "$ref": "#/definitions/mention_link_preview" },
        { "$ref": "#/definitions/mention_page" },
        { "$ref": "#/definitions/mention_template_mention" },
        { "$ref": "#/definitions/mention_user" }
      ]
    },

    "rich_text_mention": {
      "type": "object",
      "description": "Rich text object of type 'mention'",
      "properties": {
        "type": { "type": "string", "const": "mention" },
        "mention": { "$ref": "#/definitions/mention_object" },
        "annotations": { "$ref": "#/definitions/annotations" },
        "plain_text": { "type": "string" },
        "href": { "type": ["string", "null"] }
      },
      "required": ["type", "mention", "annotations", "plain_text", "href"]
    },

    "rich_text_equation": {
      "type": "object",
      "description": "Rich text object of type 'equation'",
      "properties": {
        "type": { "type": "string", "const": "equation" },
        "equation": {
          "type": "object",
          "properties": {
            "expression": { "type": "string", "description": "LaTeX expression string" }
          },
          "required": ["expression"]
        },
        "annotations": { "$ref": "#/definitions/annotations" },
        "plain_text": { "type": "string" },
        "href": { "type": ["string", "null"] }
      },
      "required": ["type", "equation", "annotations", "plain_text", "href"]
    },

    "rich_text": {
      "type": "object",
      "description": "A rich text object",
      "oneOf": [
        { "$ref": "#/definitions/rich_text_text" },
        { "$ref": "#/definitions/rich_text_mention" },
        { "$ref": "#/definitions/rich_text_equation" }
      ]
    },

    "rich_text_array": {
      "type": "array",
      "items": { "$ref": "#/definitions/rich_text" }
    },

    "file_external": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "external" },
        "external": {
          "type": "object",
          "properties": {
            "url": { "type": "string", "format": "uri" }
          },
          "required": ["url"]
        }
      },
      "required": ["type", "external"]
    },

    "file_notion_hosted": {
      "type": "object",
      "description": "Notion-hosted file with temporary URL (expires after 1 hour)",
      "properties": {
        "type": { "type": "string", "const": "file" },
        "file": {
          "type": "object",
          "properties": {
            "url": { "type": "string", "format": "uri" },
            "expiry_time": { "$ref": "#/definitions/iso8601_datetime" }
          },
          "required": ["url", "expiry_time"]
        }
      },
      "required": ["type", "file"]
    },

    "file_upload": {
      "type": "object",
      "description": "File uploaded via File Upload API",
      "properties": {
        "type": { "type": "string", "const": "file_upload" },
        "file_upload": {
          "type": "object",
          "properties": {
            "id": { "$ref": "#/definitions/uuid" }
          },
          "required": ["id"]
        }
      },
      "required": ["type", "file_upload"]
    },

    "file_object": {
      "type": "object",
      "description": "A file object (external, Notion-hosted, or uploaded)",
      "oneOf": [
        { "$ref": "#/definitions/file_external" },
        { "$ref": "#/definitions/file_notion_hosted" },
        { "$ref": "#/definitions/file_upload" }
      ]
    },

    "icon_emoji": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "emoji" },
        "emoji": { "type": "string" }
      },
      "required": ["type", "emoji"]
    },

    "icon_object": {
      "type": "object",
      "description": "An emoji or file icon",
      "oneOf": [
        { "$ref": "#/definitions/icon_emoji" },
        { "$ref": "#/definitions/file_external" },
        { "$ref": "#/definitions/file_notion_hosted" }
      ]
    },

    "synced_from": {
      "type": ["object", "null"],
      "description": "null for original synced blocks, object with block_id for duplicates",
      "properties": {
        "type": { "type": "string", "const": "block_id" },
        "block_id": { "$ref": "#/definitions/uuid" }
      },
      "required": ["type", "block_id"]
    },

    "common_block_properties": {
      "type": "object",
      "description": "Properties shared by all block objects",
      "properties": {
        "object": { "type": "string", "const": "block" },
        "id": { "$ref": "#/definitions/uuid" },
        "type": { "$ref": "#/definitions/block_type" },
        "parent": { "$ref": "#/definitions/parent" },
        "created_time": { "$ref": "#/definitions/iso8601_datetime" },
        "created_by": { "$ref": "#/definitions/partial_user" },
        "last_edited_time": { "$ref": "#/definitions/iso8601_datetime" },
        "last_edited_by": { "$ref": "#/definitions/partial_user" },
        "has_children": { "type": "boolean" },
        "in_trash": { "type": "boolean" },
        "archived": { "type": "boolean", "description": "Deprecated. Alias for in_trash." }
      },
      "required": ["object", "id", "type"]
    },

    "paragraph_block": {
      "type": "object",
      "description": "Paragraph block. Type: 'paragraph'. Supports children.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array" },
        "color": { "$ref": "#/definitions/color" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" },
          "description": "Nested child blocks (optional)"
        }
      },
      "required": ["rich_text", "color"]
    },

    "heading_block": {
      "type": "object",
      "description": "Heading block (heading_1, heading_2, heading_3). Supports children only when is_toggleable is true.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array" },
        "color": { "$ref": "#/definitions/color" },
        "is_toggleable": {
          "type": "boolean",
          "description": "Whether the heading is a toggle heading that can support children"
        },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" },
          "description": "Nested child blocks. Only present when is_toggleable is true."
        }
      },
      "required": ["rich_text", "color", "is_toggleable"]
    },

    "bulleted_list_item_block": {
      "type": "object",
      "description": "Bulleted list item block. Type: 'bulleted_list_item'. Supports children.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array" },
        "color": { "$ref": "#/definitions/color" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" }
        }
      },
      "required": ["rich_text", "color"]
    },

    "numbered_list_item_block": {
      "type": "object",
      "description": "Numbered list item block. Type: 'numbered_list_item'. Supports children.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array" },
        "color": { "$ref": "#/definitions/color" },
        "list_start_index": {
          "type": "integer",
          "description": "Start index of list. Only present on the first item when list doesn't start at 1."
        },
        "list_format": {
          "$ref": "#/definitions/list_format",
          "description": "Format of list numbering. Only present on the first list item."
        },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" }
        }
      },
      "required": ["rich_text", "color"]
    },

    "to_do_block": {
      "type": "object",
      "description": "To-do / checkbox block. Type: 'to_do'. Supports children.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array" },
        "checked": { "type": "boolean", "description": "Whether the to-do is checked" },
        "color": { "$ref": "#/definitions/color" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" }
        }
      },
      "required": ["rich_text", "color"]
    },

    "toggle_block": {
      "type": "object",
      "description": "Toggle block. Type: 'toggle'. Supports children.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array" },
        "color": { "$ref": "#/definitions/color" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" }
        }
      },
      "required": ["rich_text", "color"]
    },

    "code_block": {
      "type": "object",
      "description": "Code block. Type: 'code'.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array", "description": "The code content" },
        "caption": { "$ref": "#/definitions/rich_text_array", "description": "Optional caption" },
        "language": { "$ref": "#/definitions/code_language" }
      },
      "required": ["rich_text", "caption", "language"]
    },

    "callout_block": {
      "type": "object",
      "description": "Callout block. Type: 'callout'. Supports children.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array" },
        "icon": { "$ref": "#/definitions/icon_object" },
        "color": { "$ref": "#/definitions/color" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" }
        }
      },
      "required": ["rich_text", "icon", "color"]
    },

    "quote_block": {
      "type": "object",
      "description": "Quote block. Type: 'quote'. Supports children.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array" },
        "color": { "$ref": "#/definitions/color" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" }
        }
      },
      "required": ["rich_text", "color"]
    },

    "equation_block": {
      "type": "object",
      "description": "Equation block. Type: 'equation'. Contains KaTeX-compatible expression.",
      "properties": {
        "expression": { "type": "string", "description": "KaTeX compatible string" }
      },
      "required": ["expression"]
    },

    "divider_block": {
      "type": "object",
      "description": "Divider block. Type: 'divider'. Contains no properties.",
      "properties": {},
      "additionalProperties": false
    },

    "table_of_contents_block": {
      "type": "object",
      "description": "Table of contents block. Type: 'table_of_contents'.",
      "properties": {
        "color": { "$ref": "#/definitions/color" }
      },
      "required": ["color"]
    },

    "breadcrumb_block": {
      "type": "object",
      "description": "Breadcrumb block. Type: 'breadcrumb'. Contains no properties.",
      "properties": {},
      "additionalProperties": false
    },

    "embed_block": {
      "type": "object",
      "description": "Embed block. Type: 'embed'. Embeds external content via URL.",
      "properties": {
        "url": { "type": "string", "format": "uri" }
      },
      "required": ["url"]
    },

    "image_block": {
      "type": "object",
      "description": "Image block. Type: 'image'. Supported external formats: .bmp, .gif, .heic, .jpeg, .jpg, .png, .svg, .tif, .tiff",
      "allOf": [
        { "$ref": "#/definitions/file_object" },
        {
          "type": "object",
          "properties": {
            "caption": { "$ref": "#/definitions/rich_text_array" }
          }
        }
      ]
    },

    "video_block": {
      "type": "object",
      "description": "Video block. Type: 'video'. Supports YouTube, Vimeo, and other video sources.",
      "allOf": [
        { "$ref": "#/definitions/file_object" },
        {
          "type": "object",
          "properties": {
            "caption": { "$ref": "#/definitions/rich_text_array" }
          }
        }
      ]
    },

    "audio_block": {
      "type": "object",
      "description": "Audio block. Type: 'audio'. Supported external formats: .mp3, .wav, .ogg, .oga, .m4a",
      "allOf": [
        { "$ref": "#/definitions/file_object" },
        {
          "type": "object",
          "properties": {
            "caption": { "$ref": "#/definitions/rich_text_array" }
          }
        }
      ]
    },

    "file_block": {
      "type": "object",
      "description": "File block. Type: 'file'. Generic file attachment.",
      "allOf": [
        { "$ref": "#/definitions/file_object" },
        {
          "type": "object",
          "properties": {
            "caption": { "$ref": "#/definitions/rich_text_array" },
            "name": { "type": "string", "description": "Display name shown in the Notion UI" }
          }
        }
      ]
    },

    "pdf_block": {
      "type": "object",
      "description": "PDF block. Type: 'pdf'. Supported format: .pdf only.",
      "allOf": [
        { "$ref": "#/definitions/file_object" },
        {
          "type": "object",
          "properties": {
            "caption": { "$ref": "#/definitions/rich_text_array" }
          }
        }
      ]
    },

    "bookmark_block": {
      "type": "object",
      "description": "Bookmark block. Type: 'bookmark'.",
      "properties": {
        "url": { "type": "string", "format": "uri" },
        "caption": { "$ref": "#/definitions/rich_text_array" }
      },
      "required": ["url", "caption"]
    },

    "child_page_block": {
      "type": "object",
      "description": "Child page block. Type: 'child_page'.",
      "properties": {
        "title": { "type": "string", "description": "Plain text title of the child page" }
      },
      "required": ["title"]
    },

    "child_database_block": {
      "type": "object",
      "description": "Child database block. Type: 'child_database'.",
      "properties": {
        "title": { "type": "string", "description": "Plain text title of the child database" }
      },
      "required": ["title"]
    },

    "table_block": {
      "type": "object",
      "description": "Table block. Type: 'table'. Must contain at least one table_row child. Supports children (table_row blocks only).",
      "properties": {
        "table_width": {
          "type": "integer",
          "description": "Number of columns. Cannot be changed after creation."
        },
        "has_column_header": {
          "type": "boolean",
          "description": "When true, first row appears visually distinct"
        },
        "has_row_header": {
          "type": "boolean",
          "description": "When true, first column appears visually distinct"
        },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" },
          "description": "table_row blocks"
        }
      },
      "required": ["table_width", "has_column_header", "has_row_header"]
    },

    "table_row_block": {
      "type": "object",
      "description": "Table row block. Type: 'table_row'. Must be a child of a table block.",
      "properties": {
        "cells": {
          "type": "array",
          "description": "Array of cell contents in horizontal display order. Each cell is an array of rich text objects.",
          "items": {
            "type": "array",
            "items": { "$ref": "#/definitions/rich_text" }
          }
        }
      },
      "required": ["cells"]
    },

    "column_list_block": {
      "type": "object",
      "description": "Column list block. Type: 'column_list'. Container for column blocks. Must have at least 2 column children. Contains no own properties.",
      "properties": {
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" },
          "minItems": 2,
          "description": "column blocks"
        }
      }
    },

    "column_block": {
      "type": "object",
      "description": "Column block. Type: 'column'. Must be a child of column_list. Supports children.",
      "properties": {
        "width_ratio": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Column width relative to others (0-1). Ratios should sum to 1 across all columns. Defaults to equal width when omitted."
        },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" }
        }
      }
    },

    "synced_block_block": {
      "type": "object",
      "description": "Synced block. Type: 'synced_block'. synced_from is null for original blocks, contains block_id reference for duplicates. Content cannot be updated via API.",
      "properties": {
        "synced_from": { "$ref": "#/definitions/synced_from" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" },
          "description": "Child blocks (only present on original synced blocks where synced_from is null)"
        }
      },
      "required": ["synced_from"]
    },

    "link_preview_block": {
      "type": "object",
      "description": "Link preview block. Type: 'link_preview'. READ-ONLY: cannot be created or appended via API.",
      "properties": {
        "url": { "type": "string", "format": "uri", "description": "The originally pasted URL" }
      },
      "required": ["url"]
    },

    "link_to_page_block": {
      "type": "object",
      "description": "Link to page block. Type: 'link_to_page'. Links to an existing page, database, or comment.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["page_id", "database_id", "comment_id"]
        },
        "page_id": { "$ref": "#/definitions/uuid" },
        "database_id": { "$ref": "#/definitions/uuid" },
        "comment_id": { "$ref": "#/definitions/uuid" }
      },
      "required": ["type"]
    },

    "template_block": {
      "type": "object",
      "description": "Template button block. Type: 'template'. DEPRECATED: Creation no longer supported as of March 27, 2023.",
      "properties": {
        "rich_text": { "$ref": "#/definitions/rich_text_array", "description": "Template button title" },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/block" },
          "description": "Child blocks that are duplicated when the template is used"
        }
      },
      "required": ["rich_text"]
    },

    "meeting_notes_block": {
      "type": "object",
      "description": "Meeting notes block (formerly 'transcription'). Type: 'meeting_notes'. READ-ONLY. Available in API version 2026-03-11+.",
      "properties": {
        "title": { "$ref": "#/definitions/rich_text_array", "description": "Display name of the meeting notes session" },
        "status": { "$ref": "#/definitions/meeting_notes_status" },
        "children": {
          "type": "object",
          "properties": {
            "summary_block_id": { "$ref": "#/definitions/uuid" },
            "notes_block_id": { "$ref": "#/definitions/uuid" },
            "transcript_block_id": {
              "oneOf": [
                { "$ref": "#/definitions/uuid" },
                { "type": "null" }
              ]
            }
          }
        },
        "calendar_event": {
          "type": "object",
          "properties": {
            "start_time": { "$ref": "#/definitions/iso8601_datetime" },
            "end_time": { "$ref": "#/definitions/iso8601_datetime" },
            "attendees": {
              "type": "array",
              "items": { "$ref": "#/definitions/uuid" },
              "description": "User IDs of attendees"
            }
          }
        },
        "recording": {
          "type": "object",
          "properties": {
            "start_time": { "$ref": "#/definitions/iso8601_datetime" },
            "end_time": { "$ref": "#/definitions/iso8601_datetime" }
          }
        }
      },
      "required": ["title", "status"]
    },

    "unsupported_block": {
      "type": "object",
      "description": "Unsupported block. Type: 'unsupported'. Represents block types not yet supported by the API.",
      "properties": {}
    },

    "block": {
      "type": "object",
      "description": "A Notion block object. Combines common properties with a type-specific property object keyed by the block type name.",
      "allOf": [
        { "$ref": "#/definitions/common_block_properties" }
      ],
      "properties": {
        "paragraph": { "$ref": "#/definitions/paragraph_block" },
        "heading_1": { "$ref": "#/definitions/heading_block" },
        "heading_2": { "$ref": "#/definitions/heading_block" },
        "heading_3": { "$ref": "#/definitions/heading_block" },
        "bulleted_list_item": { "$ref": "#/definitions/bulleted_list_item_block" },
        "numbered_list_item": { "$ref": "#/definitions/numbered_list_item_block" },
        "to_do": { "$ref": "#/definitions/to_do_block" },
        "toggle": { "$ref": "#/definitions/toggle_block" },
        "code": { "$ref": "#/definitions/code_block" },
        "callout": { "$ref": "#/definitions/callout_block" },
        "quote": { "$ref": "#/definitions/quote_block" },
        "equation": { "$ref": "#/definitions/equation_block" },
        "divider": { "$ref": "#/definitions/divider_block" },
        "table_of_contents": { "$ref": "#/definitions/table_of_contents_block" },
        "breadcrumb": { "$ref": "#/definitions/breadcrumb_block" },
        "embed": { "$ref": "#/definitions/embed_block" },
        "image": { "$ref": "#/definitions/image_block" },
        "video": { "$ref": "#/definitions/video_block" },
        "audio": { "$ref": "#/definitions/audio_block" },
        "file": { "$ref": "#/definitions/file_block" },
        "pdf": { "$ref": "#/definitions/pdf_block" },
        "bookmark": { "$ref": "#/definitions/bookmark_block" },
        "child_page": { "$ref": "#/definitions/child_page_block" },
        "child_database": { "$ref": "#/definitions/child_database_block" },
        "table": { "$ref": "#/definitions/table_block" },
        "table_row": { "$ref": "#/definitions/table_row_block" },
        "column_list": { "$ref": "#/definitions/column_list_block" },
        "column": { "$ref": "#/definitions/column_block" },
        "synced_block": { "$ref": "#/definitions/synced_block_block" },
        "link_preview": { "$ref": "#/definitions/link_preview_block" },
        "link_to_page": { "$ref": "#/definitions/link_to_page_block" },
        "template": { "$ref": "#/definitions/template_block" },
        "meeting_notes": { "$ref": "#/definitions/meeting_notes_block" },
        "unsupported": { "$ref": "#/definitions/unsupported_block" }
      }
    }
  },

  "_metadata": {
    "blocks_supporting_children": [
      "bulleted_list_item",
      "callout",
      "child_database",
      "child_page",
      "column",
      "column_list",
      "heading_1 (when is_toggleable=true)",
      "heading_2 (when is_toggleable=true)",
      "heading_3 (when is_toggleable=true)",
      "meeting_notes",
      "numbered_list_item",
      "paragraph",
      "quote",
      "synced_block",
      "table",
      "template",
      "to_do",
      "toggle"
    ],
    "read_only_block_types": [
      "link_preview",
      "meeting_notes"
    ],
    "deprecated_block_types": [
      "template (creation deprecated March 27, 2023)"
    ],
    "media_supported_formats": {
      "image_external": [".bmp", ".gif", ".heic", ".jpeg", ".jpg", ".png", ".svg", ".tif", ".tiff"],
      "audio_external": [".mp3", ".wav", ".ogg", ".oga", ".m4a"],
      "video_external": ["YouTube URLs", "Vimeo URLs", "and other embeddable video sources"],
      "pdf": [".pdf"]
    },
    "file_object_types": ["external", "file", "file_upload"],
    "file_url_expiry": "Notion-hosted file URLs (type='file') expire after 1 hour. Do not cache statically.",
    "api_version_notes": "meeting_notes block type requires API version 2026-03-11 or later"
  }
}