notion_append_block_children
Add new blocks to a specified parent block in Notion. Use this tool to insert content like paragraphs, headings, lists, or other block types, and optionally position them after a specific block.
Instructions
Append new children blocks to a specified parent block in Notion. Requires insert content capabilities. You can optionally specify the 'after' parameter to append after a certain block.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | The ID of the existing block that the new block should be appended after.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| block_id | Yes | The ID of the parent block.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| children | Yes | Array of block objects to append. Each block must follow the Notion block schema. | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Input Schema (JSON Schema)
{
"properties": {
"after": {
"description": "The ID of the existing block that the new block should be appended after.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"block_id": {
"description": "The ID of the parent block.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"children": {
"description": "Array of block objects to append. Each block must follow the Notion block schema.",
"items": {
"description": "A Notion block object.",
"properties": {
"bulleted_list_item": {
"description": "Bulleted list item block object.",
"properties": {
"children": {
"description": "Nested child blocks.",
"items": {
"description": "A nested block object.",
"type": "object"
},
"type": "array"
},
"color": {
"description": "The color of the block.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"rich_text": {
"description": "Array of rich text objects representing the list item content.",
"items": {
"description": "A rich text object.",
"properties": {
"annotations": {
"description": "Styling information for the text. By default, give nothing for default text.",
"properties": {
"bold": {
"type": "boolean"
},
"code": {
"type": "boolean"
},
"color": {
"description": "Color for the text.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"italic": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"underline": {
"type": "boolean"
}
},
"type": "object"
},
"equation": {
"description": "Equation object if type is 'equation'. Represents an inline LaTeX equation.",
"properties": {
"expression": {
"description": "LaTeX string representing the inline equation.",
"type": "string"
}
},
"required": [
"expression"
],
"type": "object"
},
"href": {
"description": "The URL of any link or mention in this text, if any. Do NOT provide a NULL value, just ignore this field if there is no link or mention.",
"type": "string"
},
"mention": {
"description": "Mention object if type is 'mention'. Represents an inline mention of a database, date, link preview, page, template mention, or user.",
"oneOf": [
{
"required": [
"database"
]
},
{
"required": [
"date"
]
},
{
"required": [
"link_preview"
]
},
{
"required": [
"page"
]
},
{
"required": [
"template_mention"
]
},
{
"required": [
"user"
]
}
],
"properties": {
"database": {
"description": "Database mention object. Contains a database reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned database.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"date": {
"description": "Date mention object, containing a date property value object.",
"properties": {
"end": {
"description": "An ISO 8601 formatted end date or date-time, or null if not a range.",
"type": [
"string",
"null"
]
},
"start": {
"description": "An ISO 8601 formatted start date or date-time.",
"type": "string"
},
"time_zone": {
"description": "Time zone information for start and end. If null, times are in UTC.",
"type": [
"string",
"null"
]
}
},
"required": [
"start"
],
"type": "object"
},
"link_preview": {
"description": "Link Preview mention object, containing a URL for the link preview.",
"properties": {
"url": {
"description": "The URL for the link preview.",
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
},
"page": {
"description": "Page mention object, containing a page reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned page.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"template_mention": {
"description": "Template mention object, can be a template_mention_date or template_mention_user.",
"properties": {
"template_mention_date": {
"description": "For template_mention_date type, the date keyword.",
"enum": [
"today",
"now"
],
"type": "string"
},
"template_mention_user": {
"description": "For template_mention_user type, the user keyword.",
"enum": [
"me"
],
"type": "string"
},
"type": {
"description": "The template mention type.",
"enum": [
"template_mention_date",
"template_mention_user"
],
"type": "string"
}
},
"type": "object"
},
"type": {
"description": "The type of the mention.",
"enum": [
"database",
"date",
"link_preview",
"page",
"template_mention",
"user"
],
"type": "string"
},
"user": {
"description": "User mention object, contains a user reference.",
"properties": {
"id": {
"description": "The ID of the user.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"object": {
"description": "Should be 'user'.",
"enum": [
"user"
],
"type": "string"
}
},
"required": [
"object",
"id"
],
"type": "object"
}
},
"required": [
"type"
],
"type": "object"
},
"plain_text": {
"description": "The plain text without annotations.",
"type": "string"
},
"text": {
"description": "Object containing text content and optional link info. Required if type is 'text'.",
"properties": {
"content": {
"description": "The actual text content.",
"type": "string"
},
"link": {
"description": "Optional link object with a 'url' field. Do NOT provide a NULL value, just ignore this field no link.",
"properties": {
"url": {
"description": "The URL the text links to.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"type": {
"description": "The type of this rich text object. Possible values: text, mention, equation.",
"enum": [
"text",
"mention",
"equation"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"divider": {
"description": "Divider block object.",
"properties": {},
"type": "object"
},
"heading_1": {
"description": "Heading 1 block object.",
"properties": {
"color": {
"description": "The color of the block.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"is_toggleable": {
"description": "Whether the heading can be toggled.",
"type": "boolean"
},
"rich_text": {
"description": "Array of rich text objects representing the heading content.",
"items": {
"description": "A rich text object.",
"properties": {
"annotations": {
"description": "Styling information for the text. By default, give nothing for default text.",
"properties": {
"bold": {
"type": "boolean"
},
"code": {
"type": "boolean"
},
"color": {
"description": "Color for the text.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"italic": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"underline": {
"type": "boolean"
}
},
"type": "object"
},
"equation": {
"description": "Equation object if type is 'equation'. Represents an inline LaTeX equation.",
"properties": {
"expression": {
"description": "LaTeX string representing the inline equation.",
"type": "string"
}
},
"required": [
"expression"
],
"type": "object"
},
"href": {
"description": "The URL of any link or mention in this text, if any. Do NOT provide a NULL value, just ignore this field if there is no link or mention.",
"type": "string"
},
"mention": {
"description": "Mention object if type is 'mention'. Represents an inline mention of a database, date, link preview, page, template mention, or user.",
"oneOf": [
{
"required": [
"database"
]
},
{
"required": [
"date"
]
},
{
"required": [
"link_preview"
]
},
{
"required": [
"page"
]
},
{
"required": [
"template_mention"
]
},
{
"required": [
"user"
]
}
],
"properties": {
"database": {
"description": "Database mention object. Contains a database reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned database.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"date": {
"description": "Date mention object, containing a date property value object.",
"properties": {
"end": {
"description": "An ISO 8601 formatted end date or date-time, or null if not a range.",
"type": [
"string",
"null"
]
},
"start": {
"description": "An ISO 8601 formatted start date or date-time.",
"type": "string"
},
"time_zone": {
"description": "Time zone information for start and end. If null, times are in UTC.",
"type": [
"string",
"null"
]
}
},
"required": [
"start"
],
"type": "object"
},
"link_preview": {
"description": "Link Preview mention object, containing a URL for the link preview.",
"properties": {
"url": {
"description": "The URL for the link preview.",
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
},
"page": {
"description": "Page mention object, containing a page reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned page.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"template_mention": {
"description": "Template mention object, can be a template_mention_date or template_mention_user.",
"properties": {
"template_mention_date": {
"description": "For template_mention_date type, the date keyword.",
"enum": [
"today",
"now"
],
"type": "string"
},
"template_mention_user": {
"description": "For template_mention_user type, the user keyword.",
"enum": [
"me"
],
"type": "string"
},
"type": {
"description": "The template mention type.",
"enum": [
"template_mention_date",
"template_mention_user"
],
"type": "string"
}
},
"type": "object"
},
"type": {
"description": "The type of the mention.",
"enum": [
"database",
"date",
"link_preview",
"page",
"template_mention",
"user"
],
"type": "string"
},
"user": {
"description": "User mention object, contains a user reference.",
"properties": {
"id": {
"description": "The ID of the user.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"object": {
"description": "Should be 'user'.",
"enum": [
"user"
],
"type": "string"
}
},
"required": [
"object",
"id"
],
"type": "object"
}
},
"required": [
"type"
],
"type": "object"
},
"plain_text": {
"description": "The plain text without annotations.",
"type": "string"
},
"text": {
"description": "Object containing text content and optional link info. Required if type is 'text'.",
"properties": {
"content": {
"description": "The actual text content.",
"type": "string"
},
"link": {
"description": "Optional link object with a 'url' field. Do NOT provide a NULL value, just ignore this field no link.",
"properties": {
"url": {
"description": "The URL the text links to.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"type": {
"description": "The type of this rich text object. Possible values: text, mention, equation.",
"enum": [
"text",
"mention",
"equation"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"heading_2": {
"description": "Heading 2 block object.",
"properties": {
"color": {
"description": "The color of the block.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"is_toggleable": {
"description": "Whether the heading can be toggled.",
"type": "boolean"
},
"rich_text": {
"description": "Array of rich text objects representing the heading content.",
"items": {
"description": "A rich text object.",
"properties": {
"annotations": {
"description": "Styling information for the text. By default, give nothing for default text.",
"properties": {
"bold": {
"type": "boolean"
},
"code": {
"type": "boolean"
},
"color": {
"description": "Color for the text.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"italic": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"underline": {
"type": "boolean"
}
},
"type": "object"
},
"equation": {
"description": "Equation object if type is 'equation'. Represents an inline LaTeX equation.",
"properties": {
"expression": {
"description": "LaTeX string representing the inline equation.",
"type": "string"
}
},
"required": [
"expression"
],
"type": "object"
},
"href": {
"description": "The URL of any link or mention in this text, if any. Do NOT provide a NULL value, just ignore this field if there is no link or mention.",
"type": "string"
},
"mention": {
"description": "Mention object if type is 'mention'. Represents an inline mention of a database, date, link preview, page, template mention, or user.",
"oneOf": [
{
"required": [
"database"
]
},
{
"required": [
"date"
]
},
{
"required": [
"link_preview"
]
},
{
"required": [
"page"
]
},
{
"required": [
"template_mention"
]
},
{
"required": [
"user"
]
}
],
"properties": {
"database": {
"description": "Database mention object. Contains a database reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned database.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"date": {
"description": "Date mention object, containing a date property value object.",
"properties": {
"end": {
"description": "An ISO 8601 formatted end date or date-time, or null if not a range.",
"type": [
"string",
"null"
]
},
"start": {
"description": "An ISO 8601 formatted start date or date-time.",
"type": "string"
},
"time_zone": {
"description": "Time zone information for start and end. If null, times are in UTC.",
"type": [
"string",
"null"
]
}
},
"required": [
"start"
],
"type": "object"
},
"link_preview": {
"description": "Link Preview mention object, containing a URL for the link preview.",
"properties": {
"url": {
"description": "The URL for the link preview.",
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
},
"page": {
"description": "Page mention object, containing a page reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned page.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"template_mention": {
"description": "Template mention object, can be a template_mention_date or template_mention_user.",
"properties": {
"template_mention_date": {
"description": "For template_mention_date type, the date keyword.",
"enum": [
"today",
"now"
],
"type": "string"
},
"template_mention_user": {
"description": "For template_mention_user type, the user keyword.",
"enum": [
"me"
],
"type": "string"
},
"type": {
"description": "The template mention type.",
"enum": [
"template_mention_date",
"template_mention_user"
],
"type": "string"
}
},
"type": "object"
},
"type": {
"description": "The type of the mention.",
"enum": [
"database",
"date",
"link_preview",
"page",
"template_mention",
"user"
],
"type": "string"
},
"user": {
"description": "User mention object, contains a user reference.",
"properties": {
"id": {
"description": "The ID of the user.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"object": {
"description": "Should be 'user'.",
"enum": [
"user"
],
"type": "string"
}
},
"required": [
"object",
"id"
],
"type": "object"
}
},
"required": [
"type"
],
"type": "object"
},
"plain_text": {
"description": "The plain text without annotations.",
"type": "string"
},
"text": {
"description": "Object containing text content and optional link info. Required if type is 'text'.",
"properties": {
"content": {
"description": "The actual text content.",
"type": "string"
},
"link": {
"description": "Optional link object with a 'url' field. Do NOT provide a NULL value, just ignore this field no link.",
"properties": {
"url": {
"description": "The URL the text links to.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"type": {
"description": "The type of this rich text object. Possible values: text, mention, equation.",
"enum": [
"text",
"mention",
"equation"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"heading_3": {
"description": "Heading 3 block object.",
"properties": {
"color": {
"description": "The color of the block.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"is_toggleable": {
"description": "Whether the heading can be toggled.",
"type": "boolean"
},
"rich_text": {
"description": "Array of rich text objects representing the heading content.",
"items": {
"description": "A rich text object.",
"properties": {
"annotations": {
"description": "Styling information for the text. By default, give nothing for default text.",
"properties": {
"bold": {
"type": "boolean"
},
"code": {
"type": "boolean"
},
"color": {
"description": "Color for the text.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"italic": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"underline": {
"type": "boolean"
}
},
"type": "object"
},
"equation": {
"description": "Equation object if type is 'equation'. Represents an inline LaTeX equation.",
"properties": {
"expression": {
"description": "LaTeX string representing the inline equation.",
"type": "string"
}
},
"required": [
"expression"
],
"type": "object"
},
"href": {
"description": "The URL of any link or mention in this text, if any. Do NOT provide a NULL value, just ignore this field if there is no link or mention.",
"type": "string"
},
"mention": {
"description": "Mention object if type is 'mention'. Represents an inline mention of a database, date, link preview, page, template mention, or user.",
"oneOf": [
{
"required": [
"database"
]
},
{
"required": [
"date"
]
},
{
"required": [
"link_preview"
]
},
{
"required": [
"page"
]
},
{
"required": [
"template_mention"
]
},
{
"required": [
"user"
]
}
],
"properties": {
"database": {
"description": "Database mention object. Contains a database reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned database.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"date": {
"description": "Date mention object, containing a date property value object.",
"properties": {
"end": {
"description": "An ISO 8601 formatted end date or date-time, or null if not a range.",
"type": [
"string",
"null"
]
},
"start": {
"description": "An ISO 8601 formatted start date or date-time.",
"type": "string"
},
"time_zone": {
"description": "Time zone information for start and end. If null, times are in UTC.",
"type": [
"string",
"null"
]
}
},
"required": [
"start"
],
"type": "object"
},
"link_preview": {
"description": "Link Preview mention object, containing a URL for the link preview.",
"properties": {
"url": {
"description": "The URL for the link preview.",
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
},
"page": {
"description": "Page mention object, containing a page reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned page.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"template_mention": {
"description": "Template mention object, can be a template_mention_date or template_mention_user.",
"properties": {
"template_mention_date": {
"description": "For template_mention_date type, the date keyword.",
"enum": [
"today",
"now"
],
"type": "string"
},
"template_mention_user": {
"description": "For template_mention_user type, the user keyword.",
"enum": [
"me"
],
"type": "string"
},
"type": {
"description": "The template mention type.",
"enum": [
"template_mention_date",
"template_mention_user"
],
"type": "string"
}
},
"type": "object"
},
"type": {
"description": "The type of the mention.",
"enum": [
"database",
"date",
"link_preview",
"page",
"template_mention",
"user"
],
"type": "string"
},
"user": {
"description": "User mention object, contains a user reference.",
"properties": {
"id": {
"description": "The ID of the user.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"object": {
"description": "Should be 'user'.",
"enum": [
"user"
],
"type": "string"
}
},
"required": [
"object",
"id"
],
"type": "object"
}
},
"required": [
"type"
],
"type": "object"
},
"plain_text": {
"description": "The plain text without annotations.",
"type": "string"
},
"text": {
"description": "Object containing text content and optional link info. Required if type is 'text'.",
"properties": {
"content": {
"description": "The actual text content.",
"type": "string"
},
"link": {
"description": "Optional link object with a 'url' field. Do NOT provide a NULL value, just ignore this field no link.",
"properties": {
"url": {
"description": "The URL the text links to.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"type": {
"description": "The type of this rich text object. Possible values: text, mention, equation.",
"enum": [
"text",
"mention",
"equation"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"numbered_list_item": {
"description": "Numbered list item block object.",
"properties": {
"children": {
"description": "Nested child blocks.",
"items": {
"description": "A nested block object.",
"type": "object"
},
"type": "array"
},
"color": {
"description": "The color of the block.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"rich_text": {
"description": "Array of rich text objects representing the list item content.",
"items": {
"description": "A rich text object.",
"properties": {
"annotations": {
"description": "Styling information for the text. By default, give nothing for default text.",
"properties": {
"bold": {
"type": "boolean"
},
"code": {
"type": "boolean"
},
"color": {
"description": "Color for the text.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"italic": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"underline": {
"type": "boolean"
}
},
"type": "object"
},
"equation": {
"description": "Equation object if type is 'equation'. Represents an inline LaTeX equation.",
"properties": {
"expression": {
"description": "LaTeX string representing the inline equation.",
"type": "string"
}
},
"required": [
"expression"
],
"type": "object"
},
"href": {
"description": "The URL of any link or mention in this text, if any. Do NOT provide a NULL value, just ignore this field if there is no link or mention.",
"type": "string"
},
"mention": {
"description": "Mention object if type is 'mention'. Represents an inline mention of a database, date, link preview, page, template mention, or user.",
"oneOf": [
{
"required": [
"database"
]
},
{
"required": [
"date"
]
},
{
"required": [
"link_preview"
]
},
{
"required": [
"page"
]
},
{
"required": [
"template_mention"
]
},
{
"required": [
"user"
]
}
],
"properties": {
"database": {
"description": "Database mention object. Contains a database reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned database.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"date": {
"description": "Date mention object, containing a date property value object.",
"properties": {
"end": {
"description": "An ISO 8601 formatted end date or date-time, or null if not a range.",
"type": [
"string",
"null"
]
},
"start": {
"description": "An ISO 8601 formatted start date or date-time.",
"type": "string"
},
"time_zone": {
"description": "Time zone information for start and end. If null, times are in UTC.",
"type": [
"string",
"null"
]
}
},
"required": [
"start"
],
"type": "object"
},
"link_preview": {
"description": "Link Preview mention object, containing a URL for the link preview.",
"properties": {
"url": {
"description": "The URL for the link preview.",
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
},
"page": {
"description": "Page mention object, containing a page reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned page.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"template_mention": {
"description": "Template mention object, can be a template_mention_date or template_mention_user.",
"properties": {
"template_mention_date": {
"description": "For template_mention_date type, the date keyword.",
"enum": [
"today",
"now"
],
"type": "string"
},
"template_mention_user": {
"description": "For template_mention_user type, the user keyword.",
"enum": [
"me"
],
"type": "string"
},
"type": {
"description": "The template mention type.",
"enum": [
"template_mention_date",
"template_mention_user"
],
"type": "string"
}
},
"type": "object"
},
"type": {
"description": "The type of the mention.",
"enum": [
"database",
"date",
"link_preview",
"page",
"template_mention",
"user"
],
"type": "string"
},
"user": {
"description": "User mention object, contains a user reference.",
"properties": {
"id": {
"description": "The ID of the user.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"object": {
"description": "Should be 'user'.",
"enum": [
"user"
],
"type": "string"
}
},
"required": [
"object",
"id"
],
"type": "object"
}
},
"required": [
"type"
],
"type": "object"
},
"plain_text": {
"description": "The plain text without annotations.",
"type": "string"
},
"text": {
"description": "Object containing text content and optional link info. Required if type is 'text'.",
"properties": {
"content": {
"description": "The actual text content.",
"type": "string"
},
"link": {
"description": "Optional link object with a 'url' field. Do NOT provide a NULL value, just ignore this field no link.",
"properties": {
"url": {
"description": "The URL the text links to.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"type": {
"description": "The type of this rich text object. Possible values: text, mention, equation.",
"enum": [
"text",
"mention",
"equation"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"object": {
"description": "Should be 'block'.",
"enum": [
"block"
],
"type": "string"
},
"paragraph": {
"description": "Paragraph block object.",
"properties": {
"children": {
"description": "Nested child blocks.",
"items": {
"description": "A nested block object.",
"type": "object"
},
"type": "array"
},
"color": {
"description": "The color of the block.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"rich_text": {
"description": "Array of rich text objects representing the comment content.",
"items": {
"description": "A rich text object.",
"properties": {
"annotations": {
"description": "Styling information for the text. By default, give nothing for default text.",
"properties": {
"bold": {
"type": "boolean"
},
"code": {
"type": "boolean"
},
"color": {
"description": "Color for the text.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"italic": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"underline": {
"type": "boolean"
}
},
"type": "object"
},
"equation": {
"description": "Equation object if type is 'equation'. Represents an inline LaTeX equation.",
"properties": {
"expression": {
"description": "LaTeX string representing the inline equation.",
"type": "string"
}
},
"required": [
"expression"
],
"type": "object"
},
"href": {
"description": "The URL of any link or mention in this text, if any. Do NOT provide a NULL value, just ignore this field if there is no link or mention.",
"type": "string"
},
"mention": {
"description": "Mention object if type is 'mention'. Represents an inline mention of a database, date, link preview, page, template mention, or user.",
"oneOf": [
{
"required": [
"database"
]
},
{
"required": [
"date"
]
},
{
"required": [
"link_preview"
]
},
{
"required": [
"page"
]
},
{
"required": [
"template_mention"
]
},
{
"required": [
"user"
]
}
],
"properties": {
"database": {
"description": "Database mention object. Contains a database reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned database.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"date": {
"description": "Date mention object, containing a date property value object.",
"properties": {
"end": {
"description": "An ISO 8601 formatted end date or date-time, or null if not a range.",
"type": [
"string",
"null"
]
},
"start": {
"description": "An ISO 8601 formatted start date or date-time.",
"type": "string"
},
"time_zone": {
"description": "Time zone information for start and end. If null, times are in UTC.",
"type": [
"string",
"null"
]
}
},
"required": [
"start"
],
"type": "object"
},
"link_preview": {
"description": "Link Preview mention object, containing a URL for the link preview.",
"properties": {
"url": {
"description": "The URL for the link preview.",
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
},
"page": {
"description": "Page mention object, containing a page reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned page.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"template_mention": {
"description": "Template mention object, can be a template_mention_date or template_mention_user.",
"properties": {
"template_mention_date": {
"description": "For template_mention_date type, the date keyword.",
"enum": [
"today",
"now"
],
"type": "string"
},
"template_mention_user": {
"description": "For template_mention_user type, the user keyword.",
"enum": [
"me"
],
"type": "string"
},
"type": {
"description": "The template mention type.",
"enum": [
"template_mention_date",
"template_mention_user"
],
"type": "string"
}
},
"type": "object"
},
"type": {
"description": "The type of the mention.",
"enum": [
"database",
"date",
"link_preview",
"page",
"template_mention",
"user"
],
"type": "string"
},
"user": {
"description": "User mention object, contains a user reference.",
"properties": {
"id": {
"description": "The ID of the user.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"object": {
"description": "Should be 'user'.",
"enum": [
"user"
],
"type": "string"
}
},
"required": [
"object",
"id"
],
"type": "object"
}
},
"required": [
"type"
],
"type": "object"
},
"plain_text": {
"description": "The plain text without annotations.",
"type": "string"
},
"text": {
"description": "Object containing text content and optional link info. Required if type is 'text'.",
"properties": {
"content": {
"description": "The actual text content.",
"type": "string"
},
"link": {
"description": "Optional link object with a 'url' field. Do NOT provide a NULL value, just ignore this field no link.",
"properties": {
"url": {
"description": "The URL the text links to.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"type": {
"description": "The type of this rich text object. Possible values: text, mention, equation.",
"enum": [
"text",
"mention",
"equation"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"toggle": {
"description": "Toggle block object.",
"properties": {
"children": {
"description": "Nested child blocks that are revealed when the toggle is opened.",
"items": {
"description": "A nested block object.",
"type": "object"
},
"type": "array"
},
"color": {
"description": "The color of the block.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"rich_text": {
"description": "Array of rich text objects representing the toggle content.",
"items": {
"description": "A rich text object.",
"properties": {
"annotations": {
"description": "Styling information for the text. By default, give nothing for default text.",
"properties": {
"bold": {
"type": "boolean"
},
"code": {
"type": "boolean"
},
"color": {
"description": "Color for the text.",
"enum": [
"default",
"blue",
"blue_background",
"brown",
"brown_background",
"gray",
"gray_background",
"green",
"green_background",
"orange",
"orange_background",
"pink",
"pink_background",
"purple",
"purple_background",
"red",
"red_background",
"yellow",
"yellow_background"
],
"type": "string"
},
"italic": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"underline": {
"type": "boolean"
}
},
"type": "object"
},
"equation": {
"description": "Equation object if type is 'equation'. Represents an inline LaTeX equation.",
"properties": {
"expression": {
"description": "LaTeX string representing the inline equation.",
"type": "string"
}
},
"required": [
"expression"
],
"type": "object"
},
"href": {
"description": "The URL of any link or mention in this text, if any. Do NOT provide a NULL value, just ignore this field if there is no link or mention.",
"type": "string"
},
"mention": {
"description": "Mention object if type is 'mention'. Represents an inline mention of a database, date, link preview, page, template mention, or user.",
"oneOf": [
{
"required": [
"database"
]
},
{
"required": [
"date"
]
},
{
"required": [
"link_preview"
]
},
{
"required": [
"page"
]
},
{
"required": [
"template_mention"
]
},
{
"required": [
"user"
]
}
],
"properties": {
"database": {
"description": "Database mention object. Contains a database reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned database.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"date": {
"description": "Date mention object, containing a date property value object.",
"properties": {
"end": {
"description": "An ISO 8601 formatted end date or date-time, or null if not a range.",
"type": [
"string",
"null"
]
},
"start": {
"description": "An ISO 8601 formatted start date or date-time.",
"type": "string"
},
"time_zone": {
"description": "Time zone information for start and end. If null, times are in UTC.",
"type": [
"string",
"null"
]
}
},
"required": [
"start"
],
"type": "object"
},
"link_preview": {
"description": "Link Preview mention object, containing a URL for the link preview.",
"properties": {
"url": {
"description": "The URL for the link preview.",
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
},
"page": {
"description": "Page mention object, containing a page reference with an 'id' field.",
"properties": {
"id": {
"description": "The ID of the mentioned page.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"template_mention": {
"description": "Template mention object, can be a template_mention_date or template_mention_user.",
"properties": {
"template_mention_date": {
"description": "For template_mention_date type, the date keyword.",
"enum": [
"today",
"now"
],
"type": "string"
},
"template_mention_user": {
"description": "For template_mention_user type, the user keyword.",
"enum": [
"me"
],
"type": "string"
},
"type": {
"description": "The template mention type.",
"enum": [
"template_mention_date",
"template_mention_user"
],
"type": "string"
}
},
"type": "object"
},
"type": {
"description": "The type of the mention.",
"enum": [
"database",
"date",
"link_preview",
"page",
"template_mention",
"user"
],
"type": "string"
},
"user": {
"description": "User mention object, contains a user reference.",
"properties": {
"id": {
"description": "The ID of the user.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-).",
"type": "string"
},
"object": {
"description": "Should be 'user'.",
"enum": [
"user"
],
"type": "string"
}
},
"required": [
"object",
"id"
],
"type": "object"
}
},
"required": [
"type"
],
"type": "object"
},
"plain_text": {
"description": "The plain text without annotations.",
"type": "string"
},
"text": {
"description": "Object containing text content and optional link info. Required if type is 'text'.",
"properties": {
"content": {
"description": "The actual text content.",
"type": "string"
},
"link": {
"description": "Optional link object with a 'url' field. Do NOT provide a NULL value, just ignore this field no link.",
"properties": {
"url": {
"description": "The URL the text links to.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"type": {
"description": "The type of this rich text object. Possible values: text, mention, equation.",
"enum": [
"text",
"mention",
"equation"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"type": {
"description": "Type of the block. Possible values include 'paragraph', 'heading_1', 'heading_2', 'heading_3', 'bulleted_list_item', 'numbered_list_item', 'to_do', 'toggle', 'child_page', 'child_database', 'embed', 'callout', 'quote', 'equation', 'divider', 'table_of_contents', 'column', 'column_list', 'link_preview', 'synced_block', 'template', 'link_to_page', 'audio', 'bookmark', 'breadcrumb', 'code', 'file', 'image', 'pdf', 'video'. Not all types are supported for creation via API.",
"type": "string"
}
},
"required": [
"object",
"type"
],
"type": "object"
},
"type": "array"
},
"format": {
"default": "markdown",
"description": "Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it.",
"enum": [
"json",
"markdown"
],
"type": "string"
}
},
"required": [
"block_id",
"children"
],
"type": "object"
}