{ "openapi": "3.1.0", "info": { "title": "Notion API (Undocumented)", "version": "1.0.0", "description": "Internal/undocumented Notion API endpoints. These endpoints are not part of the public API and may change without notice. Do not rely on these for production integrations.", "termsOfService": "https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac", "x-noIndex": true }, "servers": [ { "url": "https://api.notion.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Internal", "description": "Internal/undocumented endpoints", "x-hidden": true } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "basicAuth": { "type": "http", "scheme": "basic" } }, "schemas": { "agentIdParentForBlockBasedObjectResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "agent_id", "description": "The parent type." }, "agent_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the parent agent." } }, "additionalProperties": false, "required": ["type", "agent_id"] }, "annotationRequest": { "type": "object", "properties": { "bold": { "type": "boolean", "description": "Whether the text is formatted as bold." }, "italic": { "type": "boolean", "description": "Whether the text is formatted as italic." }, "strikethrough": { "type": "boolean", "description": "Whether the text is formatted with a strikethrough." }, "underline": { "type": "boolean", "description": "Whether the text is formatted with an underline." }, "code": { "type": "boolean", "description": "Whether the text is formatted as code." }, "color": { "$ref": "#/components/schemas/apiColor", "description": "The color of the text." } } }, "annotationResponse": { "type": "object", "properties": { "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "strikethrough": { "type": "boolean" }, "underline": { "type": "boolean" }, "code": { "type": "boolean" }, "color": { "$ref": "#/components/schemas/apiColor" } }, "additionalProperties": false, "required": [ "bold", "italic", "strikethrough", "underline", "code", "color" ] }, "apiColor": { "type": "string", "enum": [ "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "default_background", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background" ], "description": "One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background`" }, "apiTranscriptionStatus": { "type": "string", "enum": [ "transcription_not_started", "transcription_paused", "transcription_in_progress", "transcription_failed", "summary_in_progress", "notes_ready" ] }, "arrayBasedPropertyValueResponse": { "oneOf": [ { "$ref": "#/components/schemas/titleArrayBasedPropertyValueResponse" }, { "$ref": "#/components/schemas/richTextArrayBasedPropertyValueResponse" }, { "$ref": "#/components/schemas/peopleArrayBasedPropertyValueResponse" }, { "$ref": "#/components/schemas/relationArrayBasedPropertyValueResponse" } ] }, "arrayPartialRollupValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "Always `array`" }, "array": { "type": "array", "items": { "$ref": "#/components/schemas/simpleOrArrayPropertyValueResponse" }, "maxItems": 100 } }, "required": ["type", "array"], "title": "Array" }, "audioBlockObjectResponse": { "title": "Audio", "type": "object", "properties": { "type": { "type": "string", "const": "audio" }, "audio": { "$ref": "#/components/schemas/mediaContentWithFileAndCaptionResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "audio", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "blockIdParentForBlockBasedObjectResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "block_id", "description": "The parent type." }, "block_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the parent block." } }, "additionalProperties": false, "required": ["type", "block_id"] }, "blockObjectResponse": { "anyOf": [ { "$ref": "#/components/schemas/paragraphBlockObjectResponse" }, { "$ref": "#/components/schemas/heading1BlockObjectResponse" }, { "$ref": "#/components/schemas/heading2BlockObjectResponse" }, { "$ref": "#/components/schemas/heading3BlockObjectResponse" }, { "$ref": "#/components/schemas/heading4BlockObjectResponse" }, { "$ref": "#/components/schemas/bulletedListItemBlockObjectResponse" }, { "$ref": "#/components/schemas/numberedListItemBlockObjectResponse" }, { "$ref": "#/components/schemas/quoteBlockObjectResponse" }, { "$ref": "#/components/schemas/toDoBlockObjectResponse" }, { "$ref": "#/components/schemas/toggleBlockObjectResponse" }, { "$ref": "#/components/schemas/templateBlockObjectResponse" }, { "$ref": "#/components/schemas/syncedBlockBlockObjectResponse" }, { "$ref": "#/components/schemas/childPageBlockObjectResponse" }, { "$ref": "#/components/schemas/childDatabaseBlockObjectResponse" }, { "$ref": "#/components/schemas/equationBlockObjectResponse" }, { "$ref": "#/components/schemas/codeBlockObjectResponse" }, { "$ref": "#/components/schemas/calloutBlockObjectResponse" }, { "$ref": "#/components/schemas/dividerBlockObjectResponse" }, { "$ref": "#/components/schemas/breadcrumbBlockObjectResponse" }, { "$ref": "#/components/schemas/tableOfContentsBlockObjectResponse" }, { "$ref": "#/components/schemas/tabBlockObjectResponse" }, { "$ref": "#/components/schemas/columnListBlockObjectResponse" }, { "$ref": "#/components/schemas/columnBlockObjectResponse" }, { "$ref": "#/components/schemas/linkToPageBlockObjectResponse" }, { "$ref": "#/components/schemas/tableBlockObjectResponse" }, { "$ref": "#/components/schemas/tableRowBlockObjectResponse" }, { "$ref": "#/components/schemas/meetingNotesBlockObjectResponse" }, { "$ref": "#/components/schemas/embedBlockObjectResponse" }, { "$ref": "#/components/schemas/bookmarkBlockObjectResponse" }, { "$ref": "#/components/schemas/imageBlockObjectResponse" }, { "$ref": "#/components/schemas/videoBlockObjectResponse" }, { "$ref": "#/components/schemas/pdfBlockObjectResponse" }, { "$ref": "#/components/schemas/fileBlockObjectResponse" }, { "$ref": "#/components/schemas/audioBlockObjectResponse" }, { "$ref": "#/components/schemas/linkPreviewBlockObjectResponse" }, { "$ref": "#/components/schemas/unsupportedBlockObjectResponse" } ] }, "bookmarkBlockObjectResponse": { "title": "Bookmark", "type": "object", "properties": { "type": { "type": "string", "const": "bookmark" }, "bookmark": { "$ref": "#/components/schemas/mediaContentWithUrlAndCaptionResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "bookmark", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "booleanFormulaPropertyResponse": { "title": "Boolean", "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "boolean": { "type": ["boolean", "null"] } }, "required": ["type", "boolean"] }, "booleanFormulaPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "Always `boolean`" }, "boolean": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "boolean"], "title": "Boolean" }, "botInfoResponse": { "type": "object", "properties": { "owner": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "user", "description": "Always `user`" }, "user": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the user." }, "object": { "type": "string", "const": "user", "description": "The user object type name." }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the user." }, "avatar_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The avatar URL of the user." }, "type": { "type": "string", "const": "person", "description": "The type of the user." }, "person": { "type": "object", "properties": { "email": { "type": "string", "description": "The email of the person." }, "email_verified": { "type": "boolean", "description": "Whether the person's email is verified." } }, "additionalProperties": false, "description": "The person info of the user." } }, "additionalProperties": false, "required": [ "id", "object", "name", "avatar_url", "type", "person" ] }, { "$ref": "#/components/schemas/partialUserObjectResponse" } ], "description": "Details about the owner of the bot, when the `type` of the owner is `user`. This means the bot is for a integration." } }, "additionalProperties": false, "required": ["type", "user"], "title": "User" }, { "type": "object", "properties": { "type": { "type": "string", "const": "workspace", "description": "Always `workspace`" }, "workspace": { "type": "boolean", "const": true, "description": "Details about the owner of the bot, when the `type` of the owner is `workspace`. This means the bot is for an internal integration." } }, "additionalProperties": false, "required": ["type", "workspace"], "title": "Workspace" } ], "description": "Details about the owner of the bot." }, "workspace_id": { "type": "string", "description": "The ID of the bot's workspace." }, "workspace_limits": { "type": "object", "properties": { "max_file_upload_size_in_bytes": { "type": "integer", "minimum": 0, "description": "The maximum allowable size of a file upload, in bytes" } }, "additionalProperties": false, "required": ["max_file_upload_size_in_bytes"], "description": "Limits and restrictions that apply to the bot's workspace" }, "workspace_name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the bot's workspace." } }, "additionalProperties": false, "required": [ "owner", "workspace_id", "workspace_limits", "workspace_name" ] }, "botUserObjectResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "bot", "description": "Indicates this user is a bot." }, "bot": { "oneOf": [ { "$ref": "#/components/schemas/emptyObject" }, { "$ref": "#/components/schemas/botInfoResponse" } ], "description": "Details about the bot, when the `type` of the user is `bot`." } }, "required": ["type", "bot"], "title": "Bot" }, "breadcrumbBlockObjectResponse": { "title": "Breadcrumb", "type": "object", "properties": { "type": { "type": "string", "const": "breadcrumb" }, "breadcrumb": { "$ref": "#/components/schemas/emptyObject" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "breadcrumb", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "bulletedListItemBlockObjectResponse": { "title": "Bulleted List Item", "type": "object", "properties": { "type": { "type": "string", "const": "bulleted_list_item" }, "bulleted_list_item": { "$ref": "#/components/schemas/contentWithRichTextAndColorResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "bulleted_list_item", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "buttonPropertyItemObjectResponse": { "title": "Button", "type": "object", "properties": { "type": { "type": "string", "const": "button" }, "button": { "$ref": "#/components/schemas/emptyObject" }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "button", "object", "id"] }, "buttonSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "button", "description": "Always `button`" }, "button": { "$ref": "#/components/schemas/emptyObject" } }, "additionalProperties": false, "required": ["type", "button"], "title": "Button" }, "calloutBlockObjectResponse": { "title": "Callout", "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "callout": { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "color": { "$ref": "#/components/schemas/apiColor" }, "icon": { "anyOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "null" } ] } }, "required": ["rich_text", "color", "icon"] }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "callout", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "checkboxDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "checkbox", "description": "Always `checkbox`" }, "checkbox": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "checkbox"], "title": "Checkbox" }, "checkboxPropertyItemObjectResponse": { "title": "Checkbox", "type": "object", "properties": { "type": { "type": "string", "const": "checkbox" }, "checkbox": { "type": "boolean" }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "checkbox", "object", "id"] }, "checkboxSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "checkbox", "description": "Always `checkbox`" }, "checkbox": { "type": "boolean" } }, "additionalProperties": false, "required": ["type", "checkbox"], "title": "Checkbox" }, "childDatabaseBlockObjectResponse": { "title": "Child Database", "type": "object", "properties": { "type": { "type": "string", "const": "child_database" }, "child_database": { "$ref": "#/components/schemas/titleObjectResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "child_database", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "childPageBlockObjectResponse": { "title": "Child Page", "type": "object", "properties": { "type": { "type": "string", "const": "child_page" }, "child_page": { "$ref": "#/components/schemas/titleObjectResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "child_page", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "codeBlockObjectResponse": { "title": "Code", "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "code": { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "caption": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "language": { "$ref": "#/components/schemas/languageRequest" } }, "required": ["rich_text", "caption", "language"] }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "code", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "columnBlockObjectResponse": { "title": "Column", "type": "object", "properties": { "type": { "type": "string", "const": "column" }, "column": { "$ref": "#/components/schemas/columnResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "column", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "columnListBlockObjectResponse": { "title": "Column List", "type": "object", "properties": { "type": { "type": "string", "const": "column_list" }, "column_list": { "$ref": "#/components/schemas/emptyObject" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "column_list", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "columnResponse": { "type": "object", "properties": { "width_ratio": { "description": "Ratio between 0 and 1 of the width of this column relative to all columns in the list. If not provided, uses an equal width.", "examples": [0.5], "type": "number" } } }, "contentWithRichTextAndColorAndListResponse": { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "color": { "$ref": "#/components/schemas/apiColor" }, "list_start_index": { "type": "integer", "minimum": 1 }, "list_format": { "$ref": "#/components/schemas/numberedListFormat" } }, "required": ["rich_text", "color"] }, "contentWithRichTextAndColorResponse": { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "color": { "$ref": "#/components/schemas/apiColor" } }, "required": ["rich_text", "color"] }, "contentWithRichTextColorAndIconResponse": { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "color": { "$ref": "#/components/schemas/apiColor" }, "icon": { "anyOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "null" } ] } }, "required": ["rich_text", "color", "icon"] }, "contentWithTableResponse": { "type": "object", "properties": { "has_column_header": { "type": "boolean" }, "has_row_header": { "type": "boolean" }, "table_width": { "type": "integer", "minimum": 1 } }, "required": ["has_column_header", "has_row_header", "table_width"] }, "contentWithTableRowResponse": { "type": "object", "properties": { "cells": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "maxItems": 100 } }, "required": ["cells"] }, "createdByDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "created_by", "description": "Always `created_by`" }, "created_by": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "created_by"], "title": "Created By" }, "createdByPropertyItemObjectResponse": { "title": "Created By", "type": "object", "properties": { "type": { "type": "string", "const": "created_by" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/partialUserObjectResponse" }, { "$ref": "#/components/schemas/userObjectResponse" } ] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "created_by", "object", "id"] }, "createdBySimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "created_by", "description": "Always `created_by`" }, "created_by": { "$ref": "#/components/schemas/userValueResponse" } }, "additionalProperties": false, "required": ["type", "created_by"], "title": "Created By" }, "createdTimeDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "created_time", "description": "Always `created_time`" }, "created_time": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "created_time"], "title": "Created Time" }, "createdTimePropertyItemObjectResponse": { "title": "Created Time", "type": "object", "properties": { "type": { "type": "string", "const": "created_time" }, "created_time": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "created_time", "object", "id"] }, "createdTimeSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "created_time", "description": "Always `created_time`" }, "created_time": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": ["type", "created_time"], "title": "Created Time" }, "customEmojiPageIconRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "custom_emoji", "description": "Always `custom_emoji`" }, "custom_emoji": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the custom emoji." }, "name": { "type": "string", "description": "The name of the custom emoji." }, "url": { "type": "string", "description": "The URL of the custom emoji." } }, "required": ["id"] } }, "required": ["custom_emoji"], "title": "Custom Emoji" }, "customEmojiPageIconResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "custom_emoji", "description": "Type of icon. In this case, a custom emoji." }, "custom_emoji": { "$ref": "#/components/schemas/customEmojiResponse", "description": "The custom emoji details for the icon." } }, "additionalProperties": false, "required": ["type", "custom_emoji"], "title": "Custom Emoji" }, "customEmojiResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the custom emoji." }, "name": { "type": "string", "description": "The name of the custom emoji." }, "url": { "type": "string", "description": "The URL of the custom emoji." } }, "additionalProperties": false, "required": ["id", "name", "url"] }, "dataSourceObjectResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "data_source", "description": "The data source object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the data source." }, "title": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100, "description": "The title of the data source." }, "description": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100, "description": "The description of the data source." }, "parent": { "$ref": "#/components/schemas/parentOfDataSourceResponse", "description": "The parent of the data source." }, "database_parent": { "$ref": "#/components/schemas/parentOfDatabaseResponse", "description": "The parent of the data source's containing database. This is typically a page, block, or workspace, but can be another database in the case of wikis." }, "is_inline": { "type": "boolean", "description": "Whether the data source is inline." }, "in_trash": { "type": "boolean", "description": "Whether the data source is in the trash." }, "created_time": { "type": "string", "format": "date-time", "description": "The time when the data source was created." }, "last_edited_time": { "type": "string", "format": "date-time", "description": "The time when the data source was last edited." }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse", "description": "The user who created the data source." }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse", "description": "The user who last edited the data source." }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/databasePropertyConfigResponse" }, "description": "The properties schema of the data source." }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "null" } ], "description": "The icon of the data source." }, "cover": { "oneOf": [ { "$ref": "#/components/schemas/pageCoverResponse" }, { "type": "null" } ], "description": "The cover of the data source." }, "url": { "type": "string", "description": "The URL of the data source." }, "public_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The public URL of the data source if it is publicly accessible." } }, "additionalProperties": false, "required": [ "object", "id", "title", "description", "parent", "database_parent", "is_inline", "in_trash", "created_time", "last_edited_time", "created_by", "last_edited_by", "properties", "icon", "cover", "url", "public_url" ] }, "dataSourceParentResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "data_source_id", "description": "The parent type." }, "data_source_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the parent data source." }, "database_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the data source's parent database." } }, "additionalProperties": false, "required": ["type", "data_source_id", "database_id"] }, "databaseParentResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "database_id", "description": "The parent type." }, "database_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the parent database." } }, "additionalProperties": false, "required": ["type", "database_id"] }, "databasePropertyConfigResponse": { "allOf": [ { "$ref": "#/components/schemas/databasePropertyConfigResponseCommon" }, { "oneOf": [ { "$ref": "#/components/schemas/numberDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/formulaDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/selectDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/multiSelectDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/statusDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/relationDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/rollupDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/uniqueIdDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/titleDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/richTextDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/urlDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/peopleDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/filesDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/emailDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/phoneNumberDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/dateDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/checkboxDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/createdByDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/createdTimeDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/lastEditedByDatabasePropertyConfigResponse" }, { "$ref": "#/components/schemas/lastEditedTimeDatabasePropertyConfigResponse" } ] } ] }, "databasePropertyConfigResponseCommon": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the property." }, "name": { "type": "string", "description": "The name of the property." }, "description": { "oneOf": [ { "$ref": "#/components/schemas/propertyDescriptionRequest" }, { "type": "null" } ], "description": "The description of the property." } }, "additionalProperties": false, "required": ["id", "name", "description"] }, "databasePropertyRelationConfigResponse": { "allOf": [ { "$ref": "#/components/schemas/databasePropertyRelationConfigResponseCommon" }, { "oneOf": [ { "$ref": "#/components/schemas/singlePropertyDatabasePropertyRelationConfigResponse" }, { "$ref": "#/components/schemas/dualPropertyDatabasePropertyRelationConfigResponse" } ] } ] }, "databasePropertyRelationConfigResponseCommon": { "type": "object", "properties": { "database_id": { "$ref": "#/components/schemas/idResponse" }, "data_source_id": { "$ref": "#/components/schemas/idResponse" } }, "additionalProperties": false, "required": ["database_id", "data_source_id"] }, "dateDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "date": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "date"], "title": "Date" }, "dateFormulaPropertyResponse": { "title": "Date", "type": "object", "properties": { "type": { "type": "string", "const": "date" }, "date": { "anyOf": [ { "$ref": "#/components/schemas/dateResponse" }, { "type": "null" } ] } }, "required": ["type", "date"] }, "dateFormulaPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "date": { "oneOf": [ { "$ref": "#/components/schemas/dateResponse" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "date"], "title": "Date" }, "datePartialRollupValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "date": { "oneOf": [ { "$ref": "#/components/schemas/dateResponse" }, { "type": "null" } ] } }, "required": ["type", "date"], "title": "Date" }, "datePropertyItemObjectResponse": { "title": "Date", "type": "object", "properties": { "type": { "type": "string", "const": "date" }, "date": { "anyOf": [ { "$ref": "#/components/schemas/dateResponse" }, { "type": "null" } ] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "date", "object", "id"] }, "dateRequest": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "description": "The start date of the date object." }, "end": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "The end date of the date object, if any." }, "time_zone": { "oneOf": [ { "$ref": "#/components/schemas/timeZoneRequest" }, { "type": "null" } ], "description": "The time zone of the date object, if any. E.g. America/Los_Angeles, Europe/London, etc." } }, "additionalProperties": false, "required": ["start"] }, "dateResponse": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "description": "The start date of the date object." }, "end": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "The end date of the date object, if any." }, "time_zone": { "oneOf": [ { "$ref": "#/components/schemas/timeZoneRequest" }, { "type": "null" } ], "description": "The time zone of the date object." } }, "additionalProperties": false, "required": ["start", "end", "time_zone"] }, "dateSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "date": { "oneOf": [ { "$ref": "#/components/schemas/dateResponse" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "date"], "title": "Date" }, "dividerBlockObjectResponse": { "title": "Divider", "type": "object", "properties": { "type": { "type": "string", "const": "divider" }, "divider": { "$ref": "#/components/schemas/emptyObject" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "divider", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "dualPropertyDatabasePropertyRelationConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "dual_property", "description": "Always `dual_property`" }, "dual_property": { "type": "object", "properties": { "synced_property_id": { "type": "string" }, "synced_property_name": { "type": "string" } }, "additionalProperties": false, "required": ["synced_property_id", "synced_property_name"] } }, "required": ["dual_property"], "title": "Dual Property" }, "emailDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "email", "description": "Always `email`" }, "email": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "email"], "title": "Email" }, "emailPropertyItemObjectResponse": { "title": "Email", "type": "object", "properties": { "type": { "type": "string", "const": "email" }, "email": { "type": ["string", "null"] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "email", "object", "id"] }, "emailSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "email", "description": "Always `email`" }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "email"], "title": "Email" }, "embedBlockObjectResponse": { "title": "Embed", "type": "object", "properties": { "type": { "type": "string", "const": "embed" }, "embed": { "$ref": "#/components/schemas/mediaContentWithUrlAndCaptionResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "embed", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "emojiPageIconRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "emoji", "description": "Always `emoji`" }, "emoji": { "$ref": "#/components/schemas/emojiRequest", "description": "An emoji character." } }, "required": ["emoji"], "title": "Emoji" }, "emojiPageIconResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "emoji", "description": "Type of icon. In this case, an emoji." }, "emoji": { "$ref": "#/components/schemas/emojiRequest", "description": "The emoji character used as the icon." } }, "additionalProperties": false, "required": ["type", "emoji"], "title": "Emoji" }, "emojiRequest": { "type": "string", "example": "😀" }, "emptyObject": { "type": "object", "properties": {}, "additionalProperties": false }, "equationBlockObjectResponse": { "title": "Equation", "type": "object", "properties": { "type": { "type": "string", "const": "equation" }, "equation": { "$ref": "#/components/schemas/expressionObjectResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "equation", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "equationRichTextItemRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "equation", "description": "Always `equation`" }, "equation": { "type": "object", "properties": { "expression": { "type": "string", "examples": ["e=mc^2"], "description": "A KaTeX compatible string." } }, "required": ["expression"], "description": "Notion supports inline LaTeX equations as rich text objects with a type value of `equation`." } }, "required": ["equation"], "title": "Equation" }, "equationRichTextItemResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "equation", "description": "Always `equation`" }, "equation": { "type": "object", "properties": { "expression": { "type": "string", "examples": ["e=mc^2"], "description": "A KaTeX compatible string." } }, "additionalProperties": false, "required": ["expression"], "description": "Notion supports inline LaTeX equations as rich text objects with a type value of `equation`." } }, "required": ["type", "equation"], "title": "Equation" }, "error_api_400": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": [ "invalid_json", "invalid_request_url", "invalid_request", "missing_version", "invalid_beta", "validation_error", "invalid_credit_limit" ] }, "status": { "const": 400 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_401": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["unauthorized"] }, "status": { "const": 401 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_403": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["restricted_resource", "status_change_not_allowed"] }, "status": { "const": 403 } }, "required": ["code", "status"], "additionalProperties": false } ] }, { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "const": "workspace_credits_exhausted" }, "status": { "const": 403 }, "additional_data": { "type": "object", "properties": { "tool_error_code": { "const": "workspace_credits_exhausted" }, "tool_error_class": { "const": "entitlement_required" }, "tool_error_retryable": { "const": "false" }, "recovery_kind": { "enum": [ "contact_workspace_owner", "open_workspace_credit_settings" ], "description": "The recovery action selected by Notion for the caller." }, "recovery_url": { "type": "string", "format": "uri", "description": "Present when recovery_kind directs the caller to a settings page." } }, "required": [ "tool_error_code", "tool_error_class", "tool_error_retryable", "recovery_kind" ], "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": ["code", "status", "additional_data"] } ] }, { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "const": "agent_credit_limit_reached" }, "status": { "const": 403 }, "additional_data": { "type": "object", "properties": { "tool_error_code": { "const": "agent_credit_limit_reached" }, "tool_error_class": { "const": "entitlement_required" }, "tool_error_retryable": { "const": "false" }, "recovery_kind": { "enum": [ "contact_workspace_owner", "none", "open_agent_settings", "request_agent_limit_increase", "request_pending" ], "description": "The recovery action selected by Notion for the caller." }, "recovery_url": { "type": "string", "format": "uri", "description": "Present when recovery_kind directs the caller to a settings page." } }, "required": [ "tool_error_code", "tool_error_class", "tool_error_retryable", "recovery_kind" ], "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": ["code", "status", "additional_data"] } ] } ] }, "error_api_404": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["object_not_found", "directory_not_found"] }, "status": { "const": 404 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_406": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["row_limit_exceeded"] }, "status": { "const": 406 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_409": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["conflict_error", "agent_deleted"] }, "status": { "const": 409 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_429": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["rate_limited"] }, "status": { "const": 429 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_500": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["internal_server_error"] }, "status": { "const": 500 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_503": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["service_unavailable"] }, "status": { "const": 503 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_504": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["gateway_timeout"] }, "status": { "const": 504 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_api_529": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["service_overload"] }, "status": { "const": 529 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_oauth_400": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": [ "invalid_request", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope" ] }, "status": { "const": 400 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_oauth_401": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["invalid_client"] }, "status": { "const": 401 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_oauth_403": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["test_env_error"] }, "status": { "const": 403 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "error_oauth_500": { "allOf": [ { "$ref": "#/components/schemas/publicApiCommonErrorResponse" }, { "type": "object", "properties": { "code": { "enum": ["internal_server_error"] }, "status": { "const": 500 } }, "required": ["code", "status"], "additionalProperties": false } ] }, "expressionObjectResponse": { "type": "object", "properties": { "expression": { "type": "string" } }, "required": ["expression"] }, "externalInternalOrExternalFileWithNameResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "external", "description": "Type of attachment. In this case, an external URL." }, "external": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the external file or resource." } }, "additionalProperties": false, "required": ["url"], "description": "The external URL." } }, "required": ["type", "external"], "title": "External" }, "externalMediaContentWithFileAndCaptionResponse": { "title": "External", "type": "object", "properties": { "type": { "type": "string", "const": "external" }, "external": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/textRequest" } }, "required": ["url"] }, "caption": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 } }, "required": ["type", "external", "caption"] }, "externalMediaContentWithFileNameAndCaptionResponse": { "title": "External", "type": "object", "properties": { "type": { "type": "string", "const": "external" }, "external": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/textRequest" } }, "required": ["url"] }, "caption": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "name": { "type": "string" } }, "required": ["type", "external", "caption", "name"] }, "externalPageCoverResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "external", "description": "Type of cover. In this case, an external URL." }, "external": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the external file or resource." } }, "additionalProperties": false, "required": ["url"], "description": "The external URL for the cover." } }, "additionalProperties": false, "required": ["type", "external"], "title": "External" }, "externalPageIconRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "external", "description": "Always `external`" }, "external": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the external file." } }, "required": ["url"] } }, "required": ["external"], "title": "External" }, "externalPageIconResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "external", "description": "Type of icon. In this case, an external URL." }, "external": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the external file or resource." } }, "additionalProperties": false, "required": ["url"], "description": "The external URL for the icon." } }, "additionalProperties": false, "required": ["type", "external"], "title": "External" }, "fileBlockObjectResponse": { "title": "File", "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "file": { "$ref": "#/components/schemas/mediaContentWithFileNameAndCaptionResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "file", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "fileInternalOrExternalFileWithNameResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "file", "description": "Type of attachment. In this case, a file uploaded to a Notion workspace." }, "file": { "$ref": "#/components/schemas/internalFileResponse", "description": "The file URL." } }, "required": ["type", "file"], "title": "File" }, "fileMediaContentWithFileAndCaptionResponse": { "title": "File", "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "file": { "$ref": "#/components/schemas/internalFileResponse" }, "caption": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 } }, "required": ["type", "file", "caption"] }, "fileMediaContentWithFileNameAndCaptionResponse": { "title": "File", "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "file": { "$ref": "#/components/schemas/internalFileResponse" }, "caption": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "name": { "type": "string" } }, "required": ["type", "file", "caption", "name"] }, "filePageCoverResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "file", "description": "Type of cover. In this case, a file." }, "file": { "$ref": "#/components/schemas/internalFileResponse", "description": "The file URL for the cover." } }, "additionalProperties": false, "required": ["type", "file"], "title": "File" }, "filePageIconResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "file", "description": "Type of icon. In this case, a file." }, "file": { "$ref": "#/components/schemas/internalFileResponse", "description": "The file URL for the icon." } }, "additionalProperties": false, "required": ["type", "file"], "title": "File" }, "fileUploadPageIconRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "file_upload", "description": "Always `file_upload`" }, "file_upload": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of a FileUpload object that has the status `uploaded`." } }, "required": ["id"] } }, "required": ["file_upload"], "title": "File Upload" }, "filesDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "files", "description": "Always `files`" }, "files": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "files"], "title": "Files" }, "filesPropertyItemObjectResponse": { "title": "Files", "type": "object", "properties": { "type": { "type": "string", "const": "files" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/internalOrExternalFileWithNameResponse" }, "maxItems": 100 }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "files", "object", "id"] }, "filesSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "files", "description": "Always `files`" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/internalOrExternalFileWithNameResponse" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "files"], "title": "Files" }, "formulaDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "formula", "description": "Always `formula`" }, "formula": { "type": "object", "properties": { "expression": { "type": "string" } }, "additionalProperties": false, "required": ["expression"] } }, "required": ["type", "formula"], "title": "Formula" }, "formulaPropertyItemObjectResponse": { "title": "Formula", "type": "object", "properties": { "type": { "type": "string", "const": "formula" }, "formula": { "$ref": "#/components/schemas/formulaPropertyResponse" }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "formula", "object", "id"] }, "formulaPropertyResponse": { "anyOf": [ { "$ref": "#/components/schemas/stringFormulaPropertyResponse" }, { "$ref": "#/components/schemas/dateFormulaPropertyResponse" }, { "$ref": "#/components/schemas/numberFormulaPropertyResponse" }, { "$ref": "#/components/schemas/booleanFormulaPropertyResponse" }, { "$ref": "#/components/schemas/unsupportedFormulaPropertyResponse" } ] }, "formulaPropertyValueResponse": { "oneOf": [ { "$ref": "#/components/schemas/booleanFormulaPropertyValueResponse" }, { "$ref": "#/components/schemas/dateFormulaPropertyValueResponse" }, { "$ref": "#/components/schemas/numberFormulaPropertyValueResponse" }, { "$ref": "#/components/schemas/stringFormulaPropertyValueResponse" }, { "$ref": "#/components/schemas/unsupportedFormulaPropertyValueResponse" } ] }, "formulaSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "formula", "description": "Always `formula`" }, "formula": { "$ref": "#/components/schemas/formulaPropertyValueResponse" } }, "additionalProperties": false, "required": ["type", "formula"], "title": "Formula" }, "groupMembershipObjectResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "group_membership", "description": "The group membership object type." }, "group_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the group." }, "member": { "type": "object", "properties": { "type": { "type": "string", "const": "user", "description": "The type of member." }, "user_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the user." } }, "additionalProperties": false, "required": ["type", "user_id"], "description": "The user that is a direct member of the group." }, "role": { "type": "string", "enum": ["owner", "member"], "description": "The user's role in the group." } }, "additionalProperties": false, "required": ["object", "group_id", "member", "role"] }, "groupObjectResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the group." }, "object": { "type": "string", "const": "group", "description": "The group object type name." }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the group." } }, "additionalProperties": false, "required": ["id", "object", "name"] }, "headerContentWithRichTextAndColorResponse": { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "color": { "$ref": "#/components/schemas/apiColor" }, "is_toggleable": { "type": "boolean" } }, "required": ["rich_text", "color", "is_toggleable"] }, "heading1BlockObjectResponse": { "title": "Heading 1", "type": "object", "properties": { "type": { "type": "string", "const": "heading_1" }, "heading_1": { "$ref": "#/components/schemas/headerContentWithRichTextAndColorResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "heading_1", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "heading2BlockObjectResponse": { "title": "Heading 2", "type": "object", "properties": { "type": { "type": "string", "const": "heading_2" }, "heading_2": { "$ref": "#/components/schemas/headerContentWithRichTextAndColorResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "heading_2", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "heading3BlockObjectResponse": { "title": "Heading 3", "type": "object", "properties": { "type": { "type": "string", "const": "heading_3" }, "heading_3": { "$ref": "#/components/schemas/headerContentWithRichTextAndColorResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "heading_3", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "heading4BlockObjectResponse": { "title": "Heading 4", "type": "object", "properties": { "type": { "type": "string", "const": "heading_4" }, "heading_4": { "$ref": "#/components/schemas/headerContentWithRichTextAndColorResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "heading_4", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "iconPageIconRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "icon", "description": "Always `icon`" }, "icon": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/noticonName", "description": "The name of the Notion icon (e.g. pizza, meeting, home). See the Notion icon picker for valid names." }, "color": { "$ref": "#/components/schemas/noticonColor", "description": "The color variant of the icon. Defaults to gray if not specified. Valid values: gray, lightgray, brown, yellow, orange, green, blue, purple, pink, red." } }, "required": ["name"], "description": "A Notion native icon, specified by name and optional color." } }, "required": ["icon"], "title": "Icon" }, "iconPageIconResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "icon", "description": "Type of icon. In this case, a Notion native icon." }, "icon": { "$ref": "#/components/schemas/noticonIconResponse", "description": "The Notion native icon, specified by name and color." } }, "additionalProperties": false, "required": ["type", "icon"], "title": "Icon" }, "idObjectResponse": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] }, "idRequest": { "type": "string" }, "idResponse": { "type": "string", "format": "uuid" }, "imageBlockObjectResponse": { "title": "Image", "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "image": { "$ref": "#/components/schemas/mediaContentWithFileAndCaptionResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "image", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "internalFileResponse": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the file." }, "expiry_time": { "type": "string", "format": "date-time", "description": "The time when the URL will expire." } }, "additionalProperties": false, "required": ["url", "expiry_time"] }, "internalOrExternalFileWithNameResponse": { "allOf": [ { "$ref": "#/components/schemas/internalOrExternalFileWithNameResponseCommon" }, { "oneOf": [ { "$ref": "#/components/schemas/fileInternalOrExternalFileWithNameResponse" }, { "$ref": "#/components/schemas/externalInternalOrExternalFileWithNameResponse" } ] } ] }, "internalOrExternalFileWithNameResponseCommon": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the file." } }, "additionalProperties": false, "required": ["name"] }, "languageRequest": { "type": "string", "enum": [ "abap", "abc", "agda", "arduino", "ascii art", "assembly", "bash", "basic", "bnf", "c", "c#", "c++", "clojure", "coffeescript", "coq", "css", "dart", "dhall", "diff", "docker", "ebnf", "elixir", "elm", "erlang", "f#", "flow", "fortran", "gherkin", "glsl", "go", "graphql", "groovy", "haskell", "hcl", "html", "idris", "java", "javascript", "json", "julia", "kotlin", "latex", "less", "lisp", "livescript", "llvm ir", "lua", "makefile", "markdown", "markup", "matlab", "mathematica", "mermaid", "nix", "notion formula", "objective-c", "ocaml", "pascal", "perl", "php", "plain text", "powershell", "prolog", "protobuf", "purescript", "python", "r", "racket", "reason", "ruby", "rust", "sass", "scala", "scheme", "scss", "shell", "smalltalk", "solidity", "sql", "swift", "toml", "typescript", "vb.net", "verilog", "vhdl", "visual basic", "webassembly", "xml", "yaml", "java/c/c++/c#" ] }, "lastEditedByDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "last_edited_by", "description": "Always `last_edited_by`" }, "last_edited_by": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "last_edited_by"], "title": "Last Edited By" }, "lastEditedByPropertyItemObjectResponse": { "title": "Last Edited By", "type": "object", "properties": { "type": { "type": "string", "const": "last_edited_by" }, "last_edited_by": { "anyOf": [ { "$ref": "#/components/schemas/partialUserObjectResponse" }, { "$ref": "#/components/schemas/userObjectResponse" } ] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "last_edited_by", "object", "id"] }, "lastEditedBySimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "last_edited_by", "description": "Always `last_edited_by`" }, "last_edited_by": { "$ref": "#/components/schemas/userValueResponse" } }, "additionalProperties": false, "required": ["type", "last_edited_by"], "title": "Last Edited By" }, "lastEditedTimeDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "last_edited_time", "description": "Always `last_edited_time`" }, "last_edited_time": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "last_edited_time"], "title": "Last Edited Time" }, "lastEditedTimePropertyItemObjectResponse": { "title": "Last Edited Time", "type": "object", "properties": { "type": { "type": "string", "const": "last_edited_time" }, "last_edited_time": { "type": "string", "format": "date-time" }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "last_edited_time", "object", "id"] }, "lastEditedTimeSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "last_edited_time", "description": "Always `last_edited_time`" }, "last_edited_time": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": ["type", "last_edited_time"], "title": "Last Edited Time" }, "linkMentionResponse": { "type": "object", "properties": { "href": { "type": "string", "description": "The href of the link mention." }, "title": { "type": "string", "description": "The title of the link." }, "description": { "type": "string", "description": "The description of the link." }, "link_author": { "type": "string", "description": "The author of the link." }, "link_provider": { "type": "string", "description": "The provider of the link." }, "thumbnail_url": { "type": "string", "description": "The thumbnail URL of the link." }, "icon_url": { "type": "string", "description": "The icon URL of the link." }, "iframe_url": { "type": "string", "description": "The iframe URL of the link." }, "height": { "type": "integer", "description": "The height of the link preview iframe." }, "padding": { "type": "integer", "description": "The padding of the link preview iframe." }, "padding_top": { "type": "integer", "description": "The top padding of the link preview iframe." } }, "additionalProperties": false, "required": ["href"] }, "linkPreviewBlockObjectResponse": { "title": "Link Preview", "type": "object", "properties": { "type": { "type": "string", "const": "link_preview" }, "link_preview": { "$ref": "#/components/schemas/mediaContentWithUrlResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "link_preview", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "linkPreviewMentionResponse": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the link preview mention." } }, "additionalProperties": false, "required": ["url"] }, "linkToPageBlockObjectResponse": { "title": "Link To Page", "type": "object", "properties": { "type": { "type": "string", "const": "link_to_page" }, "link_to_page": { "anyOf": [ { "title": "Page Id", "type": "object", "properties": { "type": { "type": "string", "const": "page_id" }, "page_id": { "$ref": "#/components/schemas/idRequest" } }, "required": ["type", "page_id"] }, { "title": "Database Id", "type": "object", "properties": { "type": { "type": "string", "const": "database_id" }, "database_id": { "$ref": "#/components/schemas/idRequest" } }, "required": ["type", "database_id"] }, { "title": "Comment Id", "type": "object", "properties": { "type": { "type": "string", "const": "comment_id" }, "comment_id": { "$ref": "#/components/schemas/idRequest" } }, "required": ["type", "comment_id"] } ] }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "link_to_page", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "mediaContentWithFileAndCaptionResponse": { "anyOf": [ { "$ref": "#/components/schemas/externalMediaContentWithFileAndCaptionResponse" }, { "$ref": "#/components/schemas/fileMediaContentWithFileAndCaptionResponse" } ] }, "mediaContentWithFileNameAndCaptionResponse": { "anyOf": [ { "$ref": "#/components/schemas/externalMediaContentWithFileNameAndCaptionResponse" }, { "$ref": "#/components/schemas/fileMediaContentWithFileNameAndCaptionResponse" } ] }, "mediaContentWithUrlAndCaptionResponse": { "type": "object", "properties": { "url": { "type": "string" }, "caption": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 } }, "required": ["url", "caption"] }, "mediaContentWithUrlResponse": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/textRequest" } }, "required": ["url"] }, "meetingNotesBlockObjectResponse": { "title": "Meeting Notes", "type": "object", "properties": { "type": { "type": "string", "const": "meeting_notes" }, "meeting_notes": { "$ref": "#/components/schemas/transcriptionBlockResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "meeting_notes", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "mentionRichTextItemRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "mention", "description": "Always `mention`" }, "mention": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "user", "description": "Always `user`" }, "user": { "$ref": "#/components/schemas/partialUserObjectRequest", "description": "Details of the user mention." } }, "required": ["user"], "title": "User" }, { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "date": { "$ref": "#/components/schemas/dateRequest", "description": "Details of the date mention." } }, "required": ["date"], "title": "Date" }, { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "page": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the page in the mention." } }, "required": ["id"], "description": "Details of the page mention." } }, "required": ["page"], "title": "Page" }, { "type": "object", "properties": { "type": { "type": "string", "const": "database", "description": "Always `database`" }, "database": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the database in the mention." } }, "required": ["id"], "description": "Details of the database mention." } }, "required": ["database"], "title": "Database" }, { "type": "object", "properties": { "type": { "type": "string", "const": "template_mention", "description": "Always `template_mention`" }, "template_mention": { "$ref": "#/components/schemas/templateMentionRequest", "description": "Details of the template mention." } }, "required": ["template_mention"], "title": "Template Mention" }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_emoji", "description": "Always `custom_emoji`" }, "custom_emoji": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the custom emoji." }, "name": { "type": "string", "description": "The name of the custom emoji." }, "url": { "type": "string", "description": "The URL of the custom emoji." } }, "required": ["id"], "description": "Details of the custom emoji mention." } }, "required": ["custom_emoji"], "title": "Custom Emoji" } ], "description": "Mention objects represent an inline mention of a database, date, link preview mention, page, template mention, or user. A mention is created in the Notion UI when a user types `@` followed by the name of the reference." } }, "required": ["mention"], "title": "Mention" }, "mentionRichTextItemResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "mention", "description": "Always `mention`" }, "mention": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "user", "description": "Always `user`" }, "user": { "$ref": "#/components/schemas/userValueResponse", "description": "Details of the user mention." } }, "additionalProperties": false, "required": ["type", "user"], "title": "User" }, { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "date": { "$ref": "#/components/schemas/dateResponse", "description": "Details of the date mention." } }, "additionalProperties": false, "required": ["type", "date"], "title": "Date" }, { "type": "object", "properties": { "type": { "type": "string", "const": "link_preview", "description": "Always `link_preview`" }, "link_preview": { "$ref": "#/components/schemas/linkPreviewMentionResponse", "description": "Details of the link preview mention." } }, "additionalProperties": false, "required": ["type", "link_preview"], "title": "Link Preview" }, { "type": "object", "properties": { "type": { "type": "string", "const": "link_mention", "description": "Always `link_mention`" }, "link_mention": { "$ref": "#/components/schemas/linkMentionResponse", "description": "Details of the link mention." } }, "additionalProperties": false, "required": ["type", "link_mention"], "title": "Link Mention" }, { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "page": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the page in the mention." } }, "additionalProperties": false, "required": ["id"], "description": "Details of the page mention." } }, "additionalProperties": false, "required": ["type", "page"], "title": "Page" }, { "type": "object", "properties": { "type": { "type": "string", "const": "database", "description": "Always `database`" }, "database": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the database in the mention." } }, "additionalProperties": false, "required": ["id"], "description": "Details of the database mention." } }, "additionalProperties": false, "required": ["type", "database"], "title": "Database" }, { "type": "object", "properties": { "type": { "type": "string", "const": "template_mention", "description": "Always `template_mention`" }, "template_mention": { "$ref": "#/components/schemas/templateMentionResponse", "description": "Details of the template mention." } }, "additionalProperties": false, "required": ["type", "template_mention"], "title": "Template Mention" }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_emoji", "description": "Always `custom_emoji`" }, "custom_emoji": { "$ref": "#/components/schemas/customEmojiResponse", "description": "Details of the custom emoji mention." } }, "additionalProperties": false, "required": ["type", "custom_emoji"], "title": "Custom Emoji" } ], "description": "Mention objects represent an inline mention of a database, date, link preview mention, page, template mention, or user. A mention is created in the Notion UI when a user types `@` followed by the name of the reference." } }, "required": ["type", "mention"], "title": "Mention" }, "multiSelectDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "multi_select", "description": "Always `multi_select`" }, "multi_select": { "type": "object", "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/selectPropertyResponse" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["options"] } }, "required": ["type", "multi_select"], "title": "Multi Select" }, "multiSelectPropertyItemObjectResponse": { "title": "Multi Select", "type": "object", "properties": { "type": { "type": "string", "const": "multi_select" }, "multi_select": { "type": "array", "items": { "$ref": "#/components/schemas/partialSelectResponse" }, "maxItems": 100 }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "multi_select", "object", "id"] }, "multiSelectSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "multi_select", "description": "Always `multi_select`" }, "multi_select": { "type": "array", "items": { "$ref": "#/components/schemas/partialSelectPropertyValueResponse" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "multi_select"], "title": "Multi Select" }, "noticonColor": { "type": "string", "enum": [ "gray", "lightgray", "brown", "yellow", "orange", "green", "blue", "purple", "pink", "red" ], "description": "One of: `gray`, `lightgray`, `brown`, `yellow`, `orange`, `green`, `blue`, `purple`, `pink`, `red`" }, "noticonIconResponse": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/noticonName", "description": "The name of the Notion icon (e.g. pizza, meeting, home). See the Notion icon picker for valid names." }, "color": { "$ref": "#/components/schemas/noticonColor", "description": "The color variant of the icon. Valid values: gray, lightgray, brown, yellow, orange, green, blue, purple, pink, red." } }, "additionalProperties": false, "required": ["name", "color"] }, "noticonName": { "type": "string", "examples": ["pizza", "meeting", "home", "star", "robot"] }, "numberDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "Always `number`" }, "number": { "type": "object", "properties": { "format": { "$ref": "#/components/schemas/numberFormat", "description": "The number format for the property." } }, "additionalProperties": false, "required": ["format"] } }, "required": ["type", "number"], "title": "Number" }, "numberFormat": { "type": "string", "example": "number" }, "numberFormulaPropertyResponse": { "title": "Number", "type": "object", "properties": { "type": { "type": "string", "const": "number" }, "number": { "type": ["number", "null"] } }, "required": ["type", "number"] }, "numberFormulaPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "Always `number`" }, "number": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "number"], "title": "Number" }, "numberPartialRollupValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "Always `number`" }, "number": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["type", "number"], "title": "Number" }, "numberPropertyItemObjectResponse": { "title": "Number", "type": "object", "properties": { "type": { "type": "string", "const": "number" }, "number": { "type": ["number", "null"] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "number", "object", "id"] }, "numberSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "Always `number`" }, "number": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "number"], "title": "Number" }, "numberedListFormat": { "type": "string", "enum": ["numbers", "letters", "roman"] }, "numberedListItemBlockObjectResponse": { "title": "Numbered List Item", "type": "object", "properties": { "type": { "type": "string", "const": "numbered_list_item" }, "numbered_list_item": { "$ref": "#/components/schemas/contentWithRichTextAndColorAndListResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "numbered_list_item", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "pageCoverResponse": { "oneOf": [ { "$ref": "#/components/schemas/filePageCoverResponse" }, { "$ref": "#/components/schemas/externalPageCoverResponse" } ] }, "pageIconRequest": { "oneOf": [ { "$ref": "#/components/schemas/fileUploadPageIconRequest" }, { "$ref": "#/components/schemas/emojiPageIconRequest" }, { "$ref": "#/components/schemas/externalPageIconRequest" }, { "$ref": "#/components/schemas/customEmojiPageIconRequest" }, { "$ref": "#/components/schemas/iconPageIconRequest" } ] }, "pageIconResponse": { "oneOf": [ { "$ref": "#/components/schemas/emojiPageIconResponse" }, { "$ref": "#/components/schemas/filePageIconResponse" }, { "$ref": "#/components/schemas/externalPageIconResponse" }, { "$ref": "#/components/schemas/customEmojiPageIconResponse" }, { "$ref": "#/components/schemas/iconPageIconResponse" } ] }, "pageIdParentForBlockBasedObjectResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "page_id", "description": "The parent type." }, "page_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the parent page." } }, "additionalProperties": false, "required": ["type", "page_id"] }, "pageObjectResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "page", "description": "The page object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the page." }, "created_time": { "type": "string", "format": "date-time", "description": "Date and time when this page was created." }, "last_edited_time": { "type": "string", "format": "date-time", "description": "Date and time when this page was last edited." }, "in_trash": { "type": "boolean", "description": "Whether the page is in trash." }, "is_archived": { "type": "boolean", "description": "Whether the page has been archived." }, "is_locked": { "type": "boolean", "description": "Whether the page is locked from editing in the Notion app UI." }, "url": { "type": "string", "description": "The URL of the Notion page." }, "public_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The public URL of the Notion page, if it has been published to the web." }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse", "description": "Information about the page's parent." }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/pagePropertyValueWithIdResponse" }, "description": "Property values of this page." }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "null" } ], "description": "Page icon." }, "cover": { "oneOf": [ { "$ref": "#/components/schemas/pageCoverResponse" }, { "type": "null" } ], "description": "Page cover image." }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse", "description": "User who created the page." }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse", "description": "User who last edited the page." } }, "additionalProperties": false, "required": [ "object", "id", "created_time", "last_edited_time", "in_trash", "is_archived", "is_locked", "url", "public_url", "parent", "properties", "icon", "cover", "created_by", "last_edited_by" ] }, "pagePropertyValueWithIdResponse": { "allOf": [ { "$ref": "#/components/schemas/idObjectResponse" }, { "oneOf": [ { "$ref": "#/components/schemas/simpleOrArrayPropertyValueResponse" }, { "$ref": "#/components/schemas/partialRollupPropertyResponse" } ] } ] }, "paragraphBlockObjectResponse": { "title": "Paragraph", "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "paragraph": { "$ref": "#/components/schemas/contentWithRichTextColorAndIconResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "paragraph", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "parentForBlockBasedObjectResponse": { "oneOf": [ { "$ref": "#/components/schemas/databaseParentResponse" }, { "$ref": "#/components/schemas/dataSourceParentResponse" }, { "$ref": "#/components/schemas/pageIdParentForBlockBasedObjectResponse" }, { "$ref": "#/components/schemas/blockIdParentForBlockBasedObjectResponse" }, { "$ref": "#/components/schemas/agentIdParentForBlockBasedObjectResponse" }, { "$ref": "#/components/schemas/workspaceParentForBlockBasedObjectResponse" } ] }, "parentOfDataSourceResponse": { "oneOf": [ { "$ref": "#/components/schemas/databaseParentResponse" }, { "$ref": "#/components/schemas/dataSourceParentResponse" } ], "description": "The parent of the data source. This is typically a database (`database_id`), but for externally synced data sources, can be another data source (`data_source_id`)." }, "parentOfDatabaseResponse": { "oneOf": [ { "$ref": "#/components/schemas/pageIdParentForBlockBasedObjectResponse" }, { "$ref": "#/components/schemas/workspaceParentForBlockBasedObjectResponse" }, { "$ref": "#/components/schemas/databaseParentResponse" }, { "$ref": "#/components/schemas/blockIdParentForBlockBasedObjectResponse" } ] }, "partialBlockObjectResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" } }, "required": ["object", "id"] }, "partialDataSourceObjectResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "data_source", "description": "The data source object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the data source." }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/databasePropertyConfigResponse" }, "description": "The properties schema of the data source." } }, "additionalProperties": false, "required": ["object", "id", "properties"] }, "partialPageObjectResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "page", "description": "The page object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the page." } }, "additionalProperties": false, "required": ["object", "id"] }, "partialRollupPropertyResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "rollup", "description": "Always `rollup`" }, "rollup": { "$ref": "#/components/schemas/partialRollupValueResponse" } }, "additionalProperties": false, "required": ["type", "rollup"] }, "partialRollupValueResponse": { "allOf": [ { "$ref": "#/components/schemas/partialRollupValueResponseCommon" }, { "oneOf": [ { "$ref": "#/components/schemas/numberPartialRollupValueResponse" }, { "$ref": "#/components/schemas/datePartialRollupValueResponse" }, { "$ref": "#/components/schemas/arrayPartialRollupValueResponse" }, { "$ref": "#/components/schemas/unsupportedPartialRollupValueResponse" } ] } ] }, "partialRollupValueResponseCommon": { "type": "object", "properties": { "function": { "$ref": "#/components/schemas/rollupFunction", "description": "The function used for the rollup, e.g. count, count_values, percent_not_empty, max." } }, "additionalProperties": false, "required": ["function"] }, "partialSelectPropertyValueResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red" ], "description": "One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`" } }, "additionalProperties": false, "required": ["id", "name", "color"] }, "partialSelectResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "$ref": "#/components/schemas/selectColor" } }, "required": ["id", "name", "color"] }, "partialUserObjectRequest": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the user." }, "object": { "type": "string", "const": "user", "description": "The user object type name." } }, "required": ["id"] }, "partialUserObjectResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "object": { "type": "string", "const": "user", "description": "Always `user`" } }, "additionalProperties": false, "required": ["id", "object"] }, "pdfBlockObjectResponse": { "title": "Pdf", "type": "object", "properties": { "type": { "type": "string", "const": "pdf" }, "pdf": { "$ref": "#/components/schemas/mediaContentWithFileAndCaptionResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "pdf", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "peopleArrayBasedPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "people", "description": "Always `people`" }, "people": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/userValueResponse" }, { "$ref": "#/components/schemas/groupObjectResponse" } ] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "people"], "title": "People" }, "peopleDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "people", "description": "Always `people`" }, "people": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "people"], "title": "People" }, "peoplePropertyItemObjectResponse": { "title": "People", "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "people": { "anyOf": [ { "$ref": "#/components/schemas/partialUserObjectResponse" }, { "$ref": "#/components/schemas/userObjectResponse" } ] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "people", "object", "id"] }, "permissionGroupObjectResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "group", "description": "The group object type." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the group." }, "name": { "type": "string", "description": "The name of the group." } }, "additionalProperties": false, "required": ["object", "id", "name"] }, "personUserObjectResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "person", "description": "Indicates this user is a person." }, "person": { "type": "object", "properties": { "email": { "type": "string", "description": "The email of the person." }, "email_verified": { "type": "boolean", "description": "Whether the person's email is verified." } }, "additionalProperties": false, "description": "Details about the person, when the `type` of the user is `person`." } }, "required": ["type", "person"], "title": "Person" }, "phoneNumberDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "phone_number", "description": "Always `phone_number`" }, "phone_number": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "phone_number"], "title": "Phone Number" }, "phoneNumberPropertyItemObjectResponse": { "title": "Phone Number", "type": "object", "properties": { "type": { "type": "string", "const": "phone_number" }, "phone_number": { "type": ["string", "null"] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "phone_number", "object", "id"] }, "phoneNumberSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "phone_number", "description": "Always `phone_number`" }, "phone_number": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "phone_number"], "title": "Phone Number" }, "placePropertyItemObjectResponse": { "title": "Place", "type": "object", "properties": { "type": { "type": "string", "const": "place" }, "place": { "type": ["object", "null"], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "name": { "type": ["string", "null"] }, "address": { "type": ["string", "null"] }, "aws_place_id": { "type": ["string", "null"] }, "google_place_id": { "type": ["string", "null"] } }, "required": ["lat", "lon"] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "place", "object", "id"] }, "placePropertyValueResponse": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "aws_place_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "google_place_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["lat", "lon"] }, "placeSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "place", "description": "Always `place`" }, "place": { "oneOf": [ { "$ref": "#/components/schemas/placePropertyValueResponse" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "place"], "title": "Place" }, "propertyDescriptionRequest": { "type": "string", "minLength": 1, "maxLength": 280 }, "propertyItemListResponse": { "$ref": "#/components/schemas/propertyItemPropertyItemListResponse" }, "propertyItemObjectResponse": { "anyOf": [ { "$ref": "#/components/schemas/numberPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/urlPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/selectPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/multiSelectPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/statusPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/datePropertyItemObjectResponse" }, { "$ref": "#/components/schemas/emailPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/phoneNumberPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/checkboxPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/filesPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/createdByPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/createdTimePropertyItemObjectResponse" }, { "$ref": "#/components/schemas/lastEditedByPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/lastEditedTimePropertyItemObjectResponse" }, { "$ref": "#/components/schemas/formulaPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/buttonPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/uniqueIdPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/verificationPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/placePropertyItemObjectResponse" }, { "$ref": "#/components/schemas/titlePropertyItemObjectResponse" }, { "$ref": "#/components/schemas/richTextPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/peoplePropertyItemObjectResponse" }, { "$ref": "#/components/schemas/relationPropertyItemObjectResponse" }, { "$ref": "#/components/schemas/rollupPropertyItemObjectResponse" } ] }, "propertyItemPropertyItemListResponse": { "title": "Property Item", "type": "object", "properties": { "type": { "type": "string", "const": "property_item" }, "property_item": { "anyOf": [ { "title": "Title", "type": "object", "properties": { "type": { "type": "string", "const": "title" }, "title": { "$ref": "#/components/schemas/emptyObject" }, "next_url": { "type": ["string", "null"] }, "id": { "type": "string" } }, "required": ["type", "title", "next_url", "id"] }, { "title": "Rich Text", "type": "object", "properties": { "type": { "type": "string", "const": "rich_text" }, "rich_text": { "$ref": "#/components/schemas/emptyObject" }, "next_url": { "type": ["string", "null"] }, "id": { "type": "string" } }, "required": ["type", "rich_text", "next_url", "id"] }, { "title": "People", "type": "object", "properties": { "type": { "type": "string", "const": "people" }, "people": { "$ref": "#/components/schemas/emptyObject" }, "next_url": { "type": ["string", "null"] }, "id": { "type": "string" } }, "required": ["type", "people", "next_url", "id"] }, { "title": "Relation", "type": "object", "properties": { "type": { "type": "string", "const": "relation" }, "relation": { "$ref": "#/components/schemas/emptyObject" }, "next_url": { "type": ["string", "null"] }, "id": { "type": "string" } }, "required": ["type", "relation", "next_url", "id"] }, { "title": "Rollup", "type": "object", "properties": { "type": { "type": "string", "const": "rollup" }, "rollup": { "anyOf": [ { "title": "Number", "type": "object", "properties": { "type": { "type": "string", "const": "number" }, "number": { "type": ["number", "null"] }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "number", "function"] }, { "title": "Date", "type": "object", "properties": { "type": { "type": "string", "const": "date" }, "date": { "anyOf": [ { "$ref": "#/components/schemas/dateResponse" }, { "type": "null" } ] }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "date", "function"] }, { "title": "Array", "type": "object", "properties": { "type": { "type": "string", "const": "array" }, "array": { "type": "array", "items": { "$ref": "#/components/schemas/emptyObject" }, "maxItems": 100 }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "array", "function"] }, { "title": "Unsupported", "type": "object", "properties": { "type": { "type": "string", "const": "unsupported" }, "unsupported": { "$ref": "#/components/schemas/emptyObject" }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "unsupported", "function"] }, { "title": "Incomplete", "type": "object", "properties": { "type": { "type": "string", "const": "incomplete" }, "incomplete": { "$ref": "#/components/schemas/emptyObject" }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "incomplete", "function"] } ] }, "next_url": { "type": ["string", "null"] }, "id": { "type": "string" } }, "required": ["type", "rollup", "next_url", "id"] } ] }, "object": { "type": "string", "const": "list" }, "next_cursor": { "type": ["string", "null"] }, "has_more": { "type": "boolean" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/propertyItemObjectResponse" } } }, "required": [ "type", "property_item", "object", "next_cursor", "has_more", "results" ] }, "publicApiCommonErrorResponse": { "type": "object", "properties": { "object": { "const": "error" }, "message": { "type": "string" }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": ["object", "message"] }, "quoteBlockObjectResponse": { "title": "Quote", "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "quote": { "$ref": "#/components/schemas/contentWithRichTextAndColorResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "quote", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "relationArrayBasedPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "relation", "description": "Always `relation`" }, "relation": { "type": "array", "items": { "$ref": "#/components/schemas/relationItemPropertyValueResponse" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "relation"], "title": "Relation" }, "relationDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "relation", "description": "Always `relation`" }, "relation": { "$ref": "#/components/schemas/databasePropertyRelationConfigResponse" } }, "required": ["type", "relation"], "title": "Relation" }, "relationItemPropertyValueResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" } }, "additionalProperties": false, "required": ["id"] }, "relationPropertyItemObjectResponse": { "title": "Relation", "type": "object", "properties": { "type": { "type": "string", "const": "relation" }, "relation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": ["id"] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "relation", "object", "id"] }, "requestStatusResponse": { "type": "object", "properties": { "type": { "type": "string", "enum": ["complete", "incomplete"], "description": "Whether the result set is complete or incomplete. `incomplete` means the response does not include all rows that match the query parameters (e.g. due to a server-side pagination depth limit)." }, "incomplete_reason": { "type": "string", "const": "query_result_limit_reached", "description": "Why the result set is incomplete. Only present when `type` is `incomplete`." } }, "additionalProperties": false, "required": ["type"] }, "richTextArrayBasedPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "rich_text", "description": "Always `rich_text`" }, "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "rich_text"], "title": "Rich Text" }, "richTextDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "rich_text", "description": "Always `rich_text`" }, "rich_text": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "rich_text"], "title": "Rich Text" }, "richTextItemRequest": { "allOf": [ { "$ref": "#/components/schemas/richTextItemRequestCommon" }, { "oneOf": [ { "$ref": "#/components/schemas/textRichTextItemRequest" }, { "$ref": "#/components/schemas/mentionRichTextItemRequest" }, { "$ref": "#/components/schemas/equationRichTextItemRequest" } ] } ] }, "richTextItemRequestCommon": { "type": "object", "properties": { "annotations": { "$ref": "#/components/schemas/annotationRequest", "description": "All rich text objects contain an annotations object that sets the styling for the rich text." } } }, "richTextItemResponse": { "allOf": [ { "$ref": "#/components/schemas/richTextItemResponseCommon" }, { "oneOf": [ { "$ref": "#/components/schemas/textRichTextItemResponse" }, { "$ref": "#/components/schemas/mentionRichTextItemResponse" }, { "$ref": "#/components/schemas/equationRichTextItemResponse" } ] } ] }, "richTextItemResponseCommon": { "type": "object", "properties": { "plain_text": { "type": "string", "description": "The plain text content of the rich text object, without any styling." }, "href": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "A URL that the rich text object links to or mentions." }, "annotations": { "$ref": "#/components/schemas/annotationResponse", "description": "All rich text objects contain an annotations object that sets the styling for the rich text." } }, "additionalProperties": false, "required": ["plain_text", "href", "annotations"] }, "richTextPropertyItemObjectResponse": { "title": "Rich Text", "type": "object", "properties": { "type": { "type": "string", "const": "rich_text" }, "rich_text": { "$ref": "#/components/schemas/richTextItemResponse" }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "rich_text", "object", "id"] }, "rollupDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "rollup", "description": "Always `rollup`" }, "rollup": { "type": "object", "properties": { "function": { "$ref": "#/components/schemas/rollupFunction", "description": "The function to use for the rollup, e.g. count, count_values, percent_not_empty, max." }, "rollup_property_name": { "type": "string" }, "relation_property_name": { "type": "string" }, "rollup_property_id": { "type": "string" }, "relation_property_id": { "type": "string" } }, "additionalProperties": false, "required": [ "function", "rollup_property_name", "relation_property_name", "rollup_property_id", "relation_property_id" ] } }, "required": ["type", "rollup"], "title": "Rollup" }, "rollupFunction": { "type": "string", "enum": [ "count", "count_values", "empty", "not_empty", "unique", "show_unique", "percent_empty", "percent_not_empty", "sum", "average", "median", "min", "max", "range", "earliest_date", "latest_date", "date_range", "checked", "unchecked", "percent_checked", "percent_unchecked", "count_per_group", "percent_per_group", "show_original" ] }, "rollupPropertyItemObjectResponse": { "title": "Rollup", "type": "object", "properties": { "type": { "type": "string", "const": "rollup" }, "rollup": { "anyOf": [ { "title": "Number", "type": "object", "properties": { "type": { "type": "string", "const": "number" }, "number": { "type": ["number", "null"] }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "number", "function"] }, { "title": "Date", "type": "object", "properties": { "type": { "type": "string", "const": "date" }, "date": { "anyOf": [ { "$ref": "#/components/schemas/dateResponse" }, { "type": "null" } ] }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "date", "function"] }, { "title": "Array", "type": "object", "properties": { "type": { "type": "string", "const": "array" }, "array": { "type": "array", "items": { "$ref": "#/components/schemas/emptyObject" }, "maxItems": 100 }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "array", "function"] }, { "title": "Unsupported", "type": "object", "properties": { "type": { "type": "string", "const": "unsupported" }, "unsupported": { "$ref": "#/components/schemas/emptyObject" }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "unsupported", "function"] }, { "title": "Incomplete", "type": "object", "properties": { "type": { "type": "string", "const": "incomplete" }, "incomplete": { "$ref": "#/components/schemas/emptyObject" }, "function": { "$ref": "#/components/schemas/rollupFunction" } }, "required": ["type", "incomplete", "function"] } ] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "rollup", "object", "id"] }, "runToolResponse": { "oneOf": [ { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } } }, "additionalProperties": false, "required": ["id", "url", "properties"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["pages"] }, { "type": "object", "properties": { "page_id": { "$ref": "#/components/schemas/idResponse" } }, "additionalProperties": false, "required": ["page_id"] }, { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page that was marked as an AI skill." } }, "required": ["page_id"] }, { "type": "object", "properties": { "result": { "type": "string" } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the created page." }, "page_url": { "type": "string", "description": "The Notion URL of the created page." } }, "additionalProperties": false, "required": ["page_id", "page_url"] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["ai_search", "workspace_search", "none"], "description": "The type of internal search that was performed, based on the user's access to Notion AI. Users without Notion AI will get a workspace search only, not including connected tools. If the search was not performed, this will be 'none'." }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "description": "Page ID for Notion results (pass to fetch tool) or full URL for external connector results." }, "type": { "type": "string" }, "highlight": { "type": "string" }, "timestamp": { "type": "string" }, "is_archived": { "type": "boolean", "description": "True when the Notion page or database is archived (directly or via an archived ancestor). Omitted otherwise." } }, "additionalProperties": false, "required": [ "id", "title", "url", "type", "highlight", "timestamp" ] }, "maxItems": 100, "description": "An array of combined and deduplicated search results from the internal search queries." } }, "additionalProperties": false, "required": ["type", "results"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "user_search", "description": "The type of users search that was performed." }, "results": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "All results of user search" } }, "additionalProperties": false, "required": ["text"] }, "maxItems": 100, "description": "An array of search results from the users search queries." } }, "additionalProperties": false, "required": ["type", "results"] }, { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "metadata": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page", "block", "folder", "database", "data_source", "self", "documentation" ], "description": "One of: `page`, `block`, `folder`, `database`, `data_source`, `self`, `documentation`" } }, "additionalProperties": false, "required": ["type"] }, "is_archived": { "type": "boolean" }, "self": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the workspace (workspace_id)." }, "name": { "type": "string", "description": "The display name of the workspace (workspace_name)." } }, "additionalProperties": false, "required": ["id", "name"], "description": "The connected Notion workspace." }, "user": { "type": "object", "properties": { "type": { "type": "string", "enum": ["person", "bot"], "description": "The type of user: 'person' or 'bot'." }, "id": { "type": "string", "description": "The unique identifier of the user." }, "name": { "type": "string", "description": "The display name of the user." }, "email": { "type": "string", "description": "The email address of the user (only for person types)." } }, "additionalProperties": false, "required": ["type", "id", "name"], "description": "The authenticated user (or bot) for this connection." }, "current_tool_access": { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "available_with_limit", "plan_required", "upgrade_required", "not_enabled" ], "description": "Whether the tool is available without a limit, available up to a plan-specific limit, requires a plan, requires an upgrade, or is disabled for this workspace." }, "landing_page_action": { "type": "string", "enum": ["start_trial", "request_trial"], "description": "The next step available from the Notion MCP landing page." }, "landing_page_url": { "type": "string", "description": "Notion MCP landing page that explains how to get full access and the available next steps." }, "upgrade_url": { "type": "string", "description": "Trackable workspace upgrade link, when upgrading can change access." } }, "additionalProperties": false, "required": ["status"] }, "description": "Map of tools visible to this MCP caller and their access state for the workspace." } }, "additionalProperties": false, "required": ["workspace", "user"], "description": "Present only when fetching id \"self\": the connected workspace and user identity." }, "truncated": { "type": "boolean" }, "unknown_block_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "unknown_block_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": ["title", "url", "text", "metadata"] }, { "type": "object", "properties": { "file_upload_id": { "$ref": "#/components/schemas/idResponse", "description": "The Public API FileUpload ID for the uploaded file." }, "filename": { "type": "string", "description": "The normalized filename stored in Notion." }, "content_type": { "type": "string", "description": "The normalized MIME type of the uploaded file." }, "content_length": { "type": "integer", "minimum": 0, "description": "The byte length of the uploaded file." }, "status": { "type": "string", "const": "uploaded", "description": "The completed upload status." }, "markdown_source": { "type": "string", "description": "An opaque source reference accepted by Notion-flavored Markdown media blocks. Attach it within one hour; unattached uploads expire and are deleted." }, "suggested_markdown": { "type": "string", "description": "A ready-to-use Notion-flavored Markdown block for placing the file on a page." } }, "additionalProperties": false, "required": [ "file_upload_id", "filename", "content_type", "content_length", "status", "markdown_source", "suggested_markdown" ] }, { "type": "object", "properties": { "file_upload_id": { "$ref": "#/components/schemas/idResponse", "description": "The FileUpload ID reserved for this upload." }, "filename": { "type": "string", "description": "The normalized filename stored in Notion." }, "content_type": { "type": "string", "description": "The normalized MIME type expected by Notion." }, "upload_url": { "type": "string", "description": "The Public API URL that accepts the single-part multipart upload." }, "upload_method": { "type": "string", "const": "POST", "description": "The HTTP method to use for the upload request." }, "upload_headers": { "type": "object", "properties": { "authorization": { "type": "string", "description": "A short-lived bearer authorization value to send with the upload request." } }, "additionalProperties": false, "required": ["authorization"], "description": "Headers to include with the upload request." }, "upload_form_field": { "type": "string", "const": "file", "description": "The multipart/form-data field in which to send the file." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the short-lived upload authorization expires." } }, "additionalProperties": false, "required": [ "file_upload_id", "filename", "content_type", "upload_url", "upload_method", "upload_headers", "upload_form_field", "expires_at" ] }, { "type": "object", "properties": { "file_upload_id": { "$ref": "#/components/schemas/idResponse", "description": "The Public API FileUpload ID that was downloaded." }, "filename": { "type": "string", "description": "The normalized filename stored in Notion." }, "content_type": { "type": "string", "description": "The normalized MIME type of the downloaded file." }, "content_length": { "type": "integer", "minimum": 0, "description": "The UTF-8 byte length of the downloaded content." }, "content": { "type": "string", "description": "The complete UTF-8 text content of the attachment." } }, "additionalProperties": false, "required": [ "file_upload_id", "filename", "content_type", "content_length", "content" ] }, { "type": "object", "properties": { "result": { "type": "string", "description": "A rendered Markdown string describing the structure and details of the newly created database." } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The canonical ID of the created Folder." }, "parent": { "oneOf": [ { "type": "object", "properties": { "page_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the page that owns the Folder." } }, "additionalProperties": false, "required": ["page_id"] }, { "type": "object", "properties": { "folder_id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the Folder that contains the created Folder." } }, "additionalProperties": false, "required": ["folder_id"] } ], "description": "The page or Folder that contains the created Folder." }, "url": { "type": "string", "description": "The canonical URL of the created Folder." } }, "additionalProperties": false, "required": ["id", "parent", "url"] }, { "type": "object", "properties": { "folder_id": { "type": "string", "description": "The ID of the updated Folder." }, "command": { "type": "string", "enum": ["add_files", "remove_files", "add_subfolder"], "description": "The Folder update that was applied." }, "updated_item_count": { "type": "integer", "minimum": 0, "description": "The number of Folder items updated." }, "created_folder_id": { "type": "string", "description": "The ID of the created nested Folder, when applicable." }, "created_folder_url": { "type": "string", "description": "The URL of the created nested Folder, when applicable." } }, "required": ["folder_id", "command", "updated_item_count"] }, { "type": "object", "properties": { "result": { "type": "string", "description": "A rendered Markdown string describing the structure and details of the updated data source." } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] } }, "maxItems": 100, "description": "Array of query result rows, where each row is a record with column names as keys" }, "has_more": { "type": "boolean", "description": "Whether there are more results available beyond the returned limit" }, "data_source_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "IDs of data sources that were queried (only present for SQL queries)" }, "next_cursor": { "type": "string", "description": "Cursor for the next page of results. Use this value as start_cursor in the next request to get the next page." }, "request_status": { "$ref": "#/components/schemas/requestStatusResponse", "description": "Set when the result set is incomplete due to a server-side query limit." } }, "additionalProperties": false, "required": ["results", "has_more"] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] } }, "maxItems": 100, "description": "Array of query result rows, where each row is a record with column names as keys" }, "has_more": { "type": "boolean", "description": "Whether there are more results available beyond the returned limit" }, "data_source_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "IDs of data sources that were queried (only present for SQL queries)" }, "next_cursor": { "type": "string", "description": "Cursor for the next page of results. Use this value as start_cursor in the next request to get the next page." }, "request_status": { "$ref": "#/components/schemas/requestStatusResponse", "description": "Set when the result set is incomplete due to a server-side query limit." } }, "additionalProperties": false, "required": ["results", "has_more"] }, { "type": "object", "properties": { "deprecation_notice": { "type": "string", "description": "Migration guidance for switching to query_data_sources with mode: \"view\"." }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] } }, "maxItems": 100, "description": "Array of query result rows, where each row is a record with column names as keys" }, "has_more": { "type": "boolean", "description": "Whether there are more results available beyond the returned limit" }, "data_source_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "IDs of data sources that were queried" }, "next_cursor": { "type": "string", "description": "Cursor for the next page of results. Use this value as start_cursor in the next request to get the next page." }, "request_status": { "$ref": "#/components/schemas/requestStatusResponse", "description": "Set when the result set is incomplete due to a server-side query limit." } }, "additionalProperties": false, "required": ["deprecation_notice", "results", "has_more"] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] } }, "maxItems": 100, "description": "Array of meeting note rows, where each row is a record with column names as keys" }, "has_more": { "type": "boolean", "description": "Whether there are more results available beyond the returned limit" } }, "additionalProperties": false, "required": ["results", "has_more"] }, { "type": "object", "properties": { "result": { "type": "object", "properties": { "status": { "type": "string", "const": "success", "description": "The status of the operation." }, "id": { "type": "string", "description": "The ID of the created comment." } }, "additionalProperties": false, "required": ["status", "id"], "description": "The result of the create comment operation." } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "text": { "type": "string", "description": "XML-formatted discussions and comments from the page." } }, "additionalProperties": false }, { "type": "object", "required": [ "object", "id", "status", "status_url", "created_time", "operation", "poll_after_seconds" ], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "async_task" }, "id": { "type": "string", "minLength": 1 }, "status_url": { "type": "string", "minLength": 1 }, "created_time": { "type": "string", "format": "date-time" }, "operation": { "type": "object", "required": ["surface", "name"], "additionalProperties": false, "properties": { "surface": { "type": "string", "enum": ["rest", "mcp"] }, "name": { "type": "string", "minLength": 1 } } }, "status": { "type": "string", "enum": ["queued", "running", "retrying"] }, "poll_after_seconds": { "type": "integer", "minimum": 0 } } }, { "type": "object", "required": [ "object", "id", "status", "status_url", "created_time", "operation", "result" ], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "async_task" }, "id": { "type": "string", "minLength": 1 }, "status_url": { "type": "string", "minLength": 1 }, "created_time": { "type": "string", "format": "date-time" }, "operation": { "type": "object", "required": ["surface", "name"], "additionalProperties": false, "properties": { "surface": { "type": "string", "enum": ["rest", "mcp"] }, "name": { "type": "string", "minLength": 1 } } }, "status": { "type": "string", "const": "succeeded" }, "result": { "type": "object" } } }, { "type": "object", "required": [ "object", "id", "status", "status_url", "created_time", "operation", "error" ], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "async_task" }, "id": { "type": "string", "minLength": 1 }, "status_url": { "type": "string", "minLength": 1 }, "created_time": { "type": "string", "format": "date-time" }, "operation": { "type": "object", "required": ["surface", "name"], "additionalProperties": false, "properties": { "surface": { "type": "string", "enum": ["rest", "mcp"] }, "name": { "type": "string", "minLength": 1 } } }, "status": { "type": "string", "const": "failed" }, "error": { "oneOf": [ { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 400 }, "code": { "type": "string", "const": "invalid_json" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 400 }, "code": { "type": "string", "const": "invalid_request_url" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 400 }, "code": { "type": "string", "const": "invalid_request" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 400 }, "code": { "type": "string", "const": "missing_version" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 400 }, "code": { "type": "string", "const": "invalid_beta" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 400 }, "code": { "type": "string", "const": "validation_error" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 401 }, "code": { "type": "string", "const": "unauthorized" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 403 }, "code": { "type": "string", "const": "restricted_resource" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 404 }, "code": { "type": "string", "const": "object_not_found" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 404 }, "code": { "type": "string", "const": "directory_not_found" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 429 }, "code": { "type": "string", "const": "rate_limited" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 529 }, "code": { "type": "string", "const": "service_overload" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 500 }, "code": { "type": "string", "const": "internal_server_error" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 503 }, "code": { "type": "string", "const": "service_unavailable" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 504 }, "code": { "type": "string", "const": "gateway_timeout" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 409 }, "code": { "type": "string", "const": "conflict_error" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 406 }, "code": { "type": "string", "const": "row_limit_exceeded" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 403 }, "code": { "type": "string", "const": "status_change_not_allowed" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 409 }, "code": { "type": "string", "const": "agent_deleted" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 400 }, "code": { "type": "string", "const": "invalid_credit_limit" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 403 }, "code": { "type": "string", "const": "workspace_credits_exhausted" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, { "type": "object", "required": ["object", "status", "code", "message"], "additionalProperties": false, "properties": { "object": { "type": "string", "const": "error" }, "status": { "type": "integer", "const": 403 }, "code": { "type": "string", "const": "agent_credit_limit_reached" }, "message": { "type": "string", "minLength": 1 }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } } ] } } }, { "type": "object", "properties": { "joinedTeams": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "team", "description": "The type of the result." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The unique identifier of the team." }, "name": { "type": "string", "description": "The display name of the team." }, "in_trash": { "type": "boolean", "description": "Whether the team is in the trash." }, "role": { "type": "string", "enum": ["owner", "member", "guest", "none"], "description": "The authenticated user's role in this team: 'owner' (full admin access), 'member' (content access), 'guest' (limited access), or 'none' (no access)." } }, "additionalProperties": false, "required": ["type", "id", "name", "in_trash", "role"] }, "maxItems": 100, "description": "Teams that the authenticated user is a member of." }, "otherTeams": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "team", "description": "The type of the result." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The unique identifier of the team." }, "name": { "type": "string", "description": "The display name of the team." }, "in_trash": { "type": "boolean", "description": "Whether the team is in the trash." }, "role": { "type": "string", "enum": ["owner", "member", "guest", "none"], "description": "The authenticated user's role in this team: 'owner' (full admin access), 'member' (content access), 'guest' (limited access), or 'none' (no access)." } }, "additionalProperties": false, "required": ["type", "id", "name", "in_trash", "role"] }, "maxItems": 100, "description": "Teams that the authenticated user is not a member of but can see." }, "hasMore": { "type": "boolean", "description": "Whether there are more teams that were not included due to the result limit." } }, "additionalProperties": false, "required": ["joinedTeams", "otherTeams", "hasMore"] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["person", "bot"], "description": "The type of user: 'person' or 'bot'." }, "id": { "type": "string", "description": "The unique identifier of the user." }, "name": { "type": "string", "description": "The display name of the user." }, "email": { "type": "string", "description": "The email address of the user (only for person types)." } }, "additionalProperties": false, "required": ["type", "id", "name"] }, "maxItems": 100, "description": "List of users (both workspace members and guests) and bots in the current page." }, "has_more": { "type": "boolean", "description": "Whether there are more users available in the next page." }, "next_cursor": { "type": "string", "description": "Cursor for the next page of results. Use this value as start_cursor in the next request to get the next page." } }, "additionalProperties": false, "required": ["results", "has_more"] }, { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "agent", "description": "The type of the result." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The unique identifier of the agent." }, "name": { "type": "string", "description": "The display name of the agent." }, "description": { "type": "string", "description": "A short description of what the agent does." }, "instructions": { "type": "string", "description": "The system instructions that define how the agent behaves." } }, "additionalProperties": false, "required": ["type", "id", "name"] }, "maxItems": 100, "description": "List of available custom agents." }, "has_more": { "type": "boolean", "description": "Whether there are more agents available in the next page." }, "next_cursor": { "type": "string", "description": "Cursor for the next page of results. Use this value as start_cursor in the next request to get the next page." } }, "additionalProperties": false, "required": ["agents", "has_more"] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Custom Agent URL accepted by spawn_session." }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["url", "name"] } }, "nextCursor": { "type": "string" } }, "additionalProperties": false, "required": ["results"] }, { "type": "object", "properties": { "matches": { "type": "array", "items": { "type": "object", "properties": { "sessionUrl": { "type": "string", "description": "The session URL for this match." }, "snippet": { "type": "string", "description": "The session excerpt that matched the question." }, "title": { "type": "string", "description": "The session's display title." }, "createdTime": { "type": "string", "description": "When the session was created, as an ISO timestamp." }, "lastEdited": { "type": "string", "description": "When the session was last active." } }, "required": ["sessionUrl", "snippet"] }, "maxItems": 100, "description": "Sessions matching the question, most relevant first." } }, "required": ["matches"] }, { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "session", "description": "Always `session`" }, "session": { "type": "object", "properties": {}, "additionalProperties": false }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "session", "description": "Always `session`" }, "id": { "type": "string" }, "agent_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ], "description": "One of: `queued`, `in_progress`, `requires_action`, `completed`, `failed`, `canceled`, `terminated`" }, "created_by": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["user", "bot"], "description": "One of: `user`, `bot`" } }, "additionalProperties": false, "required": ["id", "type"] }, "agent_version": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer", "minimum": 1 }, "published_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": ["id", "number", "published_at"] }, { "type": "null" } ] }, "models": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "auto", "description": "Always `auto`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "pinned", "description": "Always `pinned`" }, "ids": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "additionalProperties": false, "required": ["type", "ids"] } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "required_actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["approve", "reject"], "description": "One of: `approve`, `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["action_id", "title", "options"] } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false, "required": ["code", "message", "retryable"] }, "trigger_type": { "type": "string" }, "type_labels": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "chat_user_emails": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tool_types": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tool_call_count": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "credits_used": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "runs_completed": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "message_count": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "id", "agent_id", "title", "status", "created_by", "agent_version", "models", "created_at", "updated_at" ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "session", "results", "has_more", "next_cursor" ] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "url": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "database", "description": "Always `database`" }, "url": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url"] } ] } }, "nextCursor": { "type": "string" } }, "additionalProperties": false, "required": ["results"] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "url": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "database", "description": "Always `database`" }, "url": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url"] } ] } }, "nextCursor": { "type": "string" } }, "additionalProperties": false, "required": ["results"] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "url": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "database", "description": "Always `database`" }, "url": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url"] } ] } }, "nextCursor": { "type": "string" } }, "additionalProperties": false, "required": ["results"] }, { "type": "object", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "url": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "database", "description": "Always `database`" }, "url": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url"] } ] } }, "nextCursor": { "type": "string" } }, "additionalProperties": false, "required": ["results"] }, { "type": "object", "properties": { "answer": { "type": "string", "description": "The AI-generated answer to the question" } }, "additionalProperties": false, "required": ["answer"] }, { "type": "object", "properties": { "session_url": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "interrupted", "requires_action", "failed", "terminated" ], "description": "One of: `running`, `completed`, `interrupted`, `requires_action`, `failed`, `terminated`" } }, "additionalProperties": false, "required": ["session_url", "status"] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "running", "completed", "interrupted", "requires_action", "failed", "terminated" ], "description": "One of: `running`, `completed`, `interrupted`, `requires_action`, `failed`, `terminated`" } }, "additionalProperties": false, "required": ["status"] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "running", "completed", "interrupted", "requires_action", "failed", "terminated" ], "description": "One of: `running`, `completed`, `interrupted`, `requires_action`, `failed`, `terminated`" }, "message": { "type": "string" } }, "additionalProperties": false, "required": ["status"] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "running", "completed", "interrupted", "requires_action", "failed", "terminated" ], "description": "One of: `running`, `completed`, `interrupted`, `requires_action`, `failed`, `terminated`" }, "interruptRequested": { "type": "boolean" } }, "additionalProperties": false, "required": ["status", "interruptRequested"] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "running", "completed", "interrupted", "requires_action", "failed", "terminated" ], "description": "One of: `running`, `completed`, `interrupted`, `requires_action`, `failed`, `terminated`" } }, "additionalProperties": false, "required": ["status"] }, { "type": "object", "properties": { "result": { "type": "string" } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "result": { "type": "string" } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "result": { "type": "object", "properties": { "status": { "type": "string", "const": "success", "description": "The status of the operation." }, "message": { "type": "string", "description": "The posted Slack reply message." }, "url": { "type": "string", "description": "The URL of the posted Slack reply." }, "channel_id": { "type": "string", "description": "The Slack channel ID containing the reply." }, "thread_id": { "type": "string", "description": "The Slack thread URI that received the reply." }, "slack_message_id": { "type": "string", "description": "The Slack message URI for the posted reply." } }, "additionalProperties": false, "required": [ "status", "message", "url", "channel_id", "thread_id", "slack_message_id" ], "description": "The result of the Slack reply operation." } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "result": { "type": "string", "description": "A rendered Markdown string describing the newly created view." } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "result": { "type": "string", "description": "A rendered Markdown string describing the updated view." } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "result": { "type": "object", "properties": { "status": { "type": "string", "const": "success", "description": "The status of the operation." }, "searched_email_address": { "type": "string", "description": "The mailbox email address the search ran against." }, "content": { "type": "string", "description": "Formatted email search results, including thread ids usable with view-thread-content." } }, "additionalProperties": false, "required": ["status", "searched_email_address", "content"], "description": "The result of the email search." } }, "additionalProperties": false, "required": ["result"] }, { "type": "object", "properties": { "result": { "type": "object", "properties": { "status": { "type": "string", "const": "success", "description": "The status of the operation." }, "email_address": { "type": "string", "description": "The mailbox email address the thread was read from." }, "content": { "type": "string", "description": "Formatted email thread content." } }, "additionalProperties": false, "required": ["status", "email_address", "content"], "description": "The result of the thread read." } }, "additionalProperties": false, "required": ["result"] } ] }, "selectColor": { "type": "string", "enum": [ "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red" ], "description": "One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`" }, "selectDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "select", "description": "Always `select`" }, "select": { "type": "object", "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/selectPropertyResponse" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["options"] } }, "required": ["type", "select"], "title": "Select" }, "selectPropertyItemObjectResponse": { "title": "Select", "type": "object", "properties": { "type": { "type": "string", "const": "select" }, "select": { "anyOf": [ { "$ref": "#/components/schemas/partialSelectResponse" }, { "type": "null" } ] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "select", "object", "id"] }, "selectPropertyResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "$ref": "#/components/schemas/selectColor" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["id", "name", "color", "description"] }, "selectSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "select", "description": "Always `select`" }, "select": { "oneOf": [ { "$ref": "#/components/schemas/partialSelectPropertyValueResponse" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "select"], "title": "Select" }, "simpleOrArrayPropertyValueResponse": { "oneOf": [ { "$ref": "#/components/schemas/simplePropertyValueResponse" }, { "$ref": "#/components/schemas/arrayBasedPropertyValueResponse" } ] }, "simplePropertyValueResponse": { "oneOf": [ { "$ref": "#/components/schemas/numberSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/urlSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/selectSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/multiSelectSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/statusSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/dateSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/emailSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/phoneNumberSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/checkboxSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/filesSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/createdBySimplePropertyValueResponse" }, { "$ref": "#/components/schemas/createdTimeSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/lastEditedBySimplePropertyValueResponse" }, { "$ref": "#/components/schemas/lastEditedTimeSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/formulaSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/buttonSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/uniqueIdSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/verificationSimplePropertyValueResponse" }, { "$ref": "#/components/schemas/placeSimplePropertyValueResponse" } ] }, "singlePropertyDatabasePropertyRelationConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "single_property", "description": "Always `single_property`" }, "single_property": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "single_property"], "title": "Single Property" }, "statusDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "status", "description": "Always `status`" }, "status": { "type": "object", "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/statusPropertyResponse" }, "maxItems": 100, "description": "The options for the status property." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the status group." }, "name": { "type": "string", "description": "The name of the status group." }, "color": { "$ref": "#/components/schemas/selectColor", "description": "The color of the status group." }, "option_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "The IDs of the status options in this group." } }, "additionalProperties": false, "required": ["id", "name", "color", "option_ids"] }, "maxItems": 100, "description": "The groups for the status property." } }, "additionalProperties": false, "required": ["options", "groups"] } }, "required": ["type", "status"], "title": "Status" }, "statusPropertyItemObjectResponse": { "title": "Status", "type": "object", "properties": { "type": { "type": "string", "const": "status" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/partialSelectResponse" }, { "type": "null" } ] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "status", "object", "id"] }, "statusPropertyResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the status option." }, "name": { "type": "string", "description": "The name of the status option." }, "color": { "$ref": "#/components/schemas/selectColor", "description": "The color of the status option." }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The description of the status option." } }, "additionalProperties": false, "required": ["id", "name", "color", "description"] }, "statusSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "status", "description": "Always `status`" }, "status": { "oneOf": [ { "$ref": "#/components/schemas/partialSelectPropertyValueResponse" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "status"], "title": "Status" }, "stringFormulaPropertyResponse": { "title": "String", "type": "object", "properties": { "type": { "type": "string", "const": "string" }, "string": { "type": ["string", "null"] } }, "required": ["type", "string"] }, "stringFormulaPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "Always `string`" }, "string": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "string"], "title": "String" }, "stringRequest": { "type": "string", "maxLength": 100, "minLength": 1 }, "syncedBlockBlockObjectResponse": { "title": "Synced Block", "type": "object", "properties": { "type": { "type": "string", "const": "synced_block" }, "synced_block": { "type": "object", "properties": { "synced_from": { "title": "Block Id", "type": ["object", "null"], "properties": { "type": { "type": "string", "const": "block_id" }, "block_id": { "$ref": "#/components/schemas/idRequest" } }, "required": ["type", "block_id"] } }, "required": ["synced_from"] }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "synced_block", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "tabBlockObjectResponse": { "title": "Tab", "type": "object", "properties": { "type": { "type": "string", "const": "tab" }, "tab": { "$ref": "#/components/schemas/emptyObject" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "tab", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "tableBlockObjectResponse": { "title": "Table", "type": "object", "properties": { "type": { "type": "string", "const": "table" }, "table": { "$ref": "#/components/schemas/contentWithTableResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "table", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "tableOfContentsBlockObjectResponse": { "title": "Table Of Contents", "type": "object", "properties": { "type": { "type": "string", "const": "table_of_contents" }, "table_of_contents": { "type": "object", "properties": { "color": { "$ref": "#/components/schemas/apiColor" } }, "required": ["color"] }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "table_of_contents", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "tableRowBlockObjectResponse": { "title": "Table Row", "type": "object", "properties": { "type": { "type": "string", "const": "table_row" }, "table_row": { "$ref": "#/components/schemas/contentWithTableRowResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "table_row", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "templateBlockObjectResponse": { "title": "Template", "type": "object", "properties": { "type": { "type": "string", "const": "template" }, "template": { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 } }, "required": ["rich_text"] }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "template", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "templateMentionDateTemplateMentionRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "template_mention_date", "description": "Always `template_mention_date`" }, "template_mention_date": { "type": "string", "enum": ["today", "now"], "description": "The date of the template mention." } }, "additionalProperties": false, "required": ["template_mention_date"], "title": "Template Mention Date" }, "templateMentionDateTemplateMentionResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "template_mention_date", "description": "Always `template_mention_date`" }, "template_mention_date": { "type": "string", "enum": ["today", "now"], "description": "The date of the template mention." } }, "additionalProperties": false, "required": ["type", "template_mention_date"], "title": "Template Mention Date" }, "templateMentionRequest": { "oneOf": [ { "$ref": "#/components/schemas/templateMentionDateTemplateMentionRequest" }, { "$ref": "#/components/schemas/templateMentionUserTemplateMentionRequest" } ] }, "templateMentionResponse": { "oneOf": [ { "$ref": "#/components/schemas/templateMentionDateTemplateMentionResponse" }, { "$ref": "#/components/schemas/templateMentionUserTemplateMentionResponse" } ] }, "templateMentionUserTemplateMentionRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "template_mention_user", "description": "Always `template_mention_user`" }, "template_mention_user": { "type": "string", "const": "me", "description": "The user of the template mention." } }, "additionalProperties": false, "required": ["template_mention_user"], "title": "Template Mention User" }, "templateMentionUserTemplateMentionResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "template_mention_user", "description": "Always `template_mention_user`" }, "template_mention_user": { "type": "string", "const": "me", "description": "The user of the template mention." } }, "additionalProperties": false, "required": ["type", "template_mention_user"], "title": "Template Mention User" }, "textRequest": { "type": "string", "maxLength": 2000, "minLength": 1 }, "textRichTextItemRequest": { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Always `text`" }, "text": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 2000, "description": "The actual text content of the text." }, "link": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "examples": ["https://www.notion.com"], "description": "The URL of the link." } }, "required": ["url"] }, { "type": "null" } ], "description": "An object with information about any inline link in this text, if included." } }, "additionalProperties": false, "required": ["content"], "description": "If a rich text object's type value is `text`, then the corresponding text field contains an object including the text content and any inline link." } }, "required": ["text"], "title": "Text" }, "textRichTextItemResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Always `text`" }, "text": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 2000, "description": "The actual text content of the text." }, "link": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "examples": ["https://www.notion.com"], "description": "The URL of the link." } }, "additionalProperties": false, "required": ["url"] }, { "type": "null" } ], "description": "An object with information about any inline link in this text, if included." } }, "additionalProperties": false, "required": ["content", "link"], "description": "If a rich text object's type value is `text`, then the corresponding text field contains an object including the text content and any inline link." } }, "required": ["type", "text"], "title": "Text" }, "timeZoneRequest": { "type": "string", "example": "Africa/Abidjan" }, "titleArrayBasedPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "title", "description": "Always `title`" }, "title": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "title"], "title": "Title" }, "titleDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "title", "description": "Always `title`" }, "title": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "title"], "title": "Title" }, "titleObjectResponse": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"] }, "titlePropertyItemObjectResponse": { "title": "Title", "type": "object", "properties": { "type": { "type": "string", "const": "title" }, "title": { "$ref": "#/components/schemas/richTextItemResponse" }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "title", "object", "id"] }, "toDoBlockObjectResponse": { "title": "To Do", "type": "object", "properties": { "type": { "type": "string", "const": "to_do" }, "to_do": { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "color": { "$ref": "#/components/schemas/apiColor" }, "checked": { "type": "boolean" } }, "required": ["rich_text", "color", "checked"] }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "to_do", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "toggleBlockObjectResponse": { "title": "Toggle", "type": "object", "properties": { "type": { "type": "string", "const": "toggle" }, "toggle": { "$ref": "#/components/schemas/contentWithRichTextAndColorResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "toggle", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "transcriptionBlockResponse": { "type": "object", "properties": { "title": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemResponse" }, "maxItems": 100 }, "status": { "$ref": "#/components/schemas/apiTranscriptionStatus" }, "children": { "$ref": "#/components/schemas/transcriptionChildrenResponse" }, "calendar_event": { "$ref": "#/components/schemas/transcriptionCalendarEventResponse" }, "recording": { "$ref": "#/components/schemas/transcriptionRecordingResponse" } } }, "transcriptionCalendarEventResponse": { "type": "object", "properties": { "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/idRequest" }, "maxItems": 100 } }, "required": ["start_time", "end_time"] }, "transcriptionChildrenResponse": { "type": "object", "properties": { "summary_block_id": { "$ref": "#/components/schemas/idRequest" }, "notes_block_id": { "$ref": "#/components/schemas/idRequest" }, "transcript_block_id": { "$ref": "#/components/schemas/idRequest" } } }, "transcriptionRecordingResponse": { "type": "object", "properties": { "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" } } }, "uniqueIdDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "unique_id", "description": "Always `unique_id`" }, "unique_id": { "type": "object", "properties": { "prefix": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The prefix for the unique ID." } }, "additionalProperties": false, "required": ["prefix"] } }, "required": ["type", "unique_id"], "title": "Unique Id" }, "uniqueIdPropertyItemObjectResponse": { "title": "Unique Id", "type": "object", "properties": { "type": { "type": "string", "const": "unique_id" }, "unique_id": { "type": "object", "properties": { "prefix": { "type": ["string", "null"] }, "number": { "type": ["number", "null"] } }, "required": ["prefix", "number"] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "unique_id", "object", "id"] }, "uniqueIdPropertyValueResponse": { "type": "object", "properties": { "prefix": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "number": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["prefix", "number"] }, "uniqueIdSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "unique_id", "description": "Always `unique_id`" }, "unique_id": { "$ref": "#/components/schemas/uniqueIdPropertyValueResponse" } }, "additionalProperties": false, "required": ["type", "unique_id"], "title": "Unique Id" }, "unsupportedBlockObjectResponse": { "title": "Unsupported", "type": "object", "properties": { "type": { "type": "string", "const": "unsupported" }, "unsupported": { "type": "object", "properties": { "block_type": { "description": "The underlying block type that is not currently supported by the Public API. Example values include: form, button, drive.", "type": "string" } }, "required": ["block_type"] }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "unsupported", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "unsupportedFormulaPropertyResponse": { "title": "Unsupported", "type": "object", "properties": { "type": { "type": "string", "const": "unsupported" }, "unsupported": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "unsupported"] }, "unsupportedFormulaPropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "unsupported", "description": "Always `unsupported`" }, "unsupported": { "$ref": "#/components/schemas/emptyObject" } }, "additionalProperties": false, "required": ["type", "unsupported"], "title": "Unsupported" }, "unsupportedPartialRollupValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "unsupported", "description": "Always `unsupported`" }, "unsupported": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "unsupported"], "title": "Unsupported" }, "urlDatabasePropertyConfigResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "url", "description": "Always `url`" }, "url": { "$ref": "#/components/schemas/emptyObject" } }, "required": ["type", "url"], "title": "Url" }, "urlPropertyItemObjectResponse": { "title": "Url", "type": "object", "properties": { "type": { "type": "string", "const": "url" }, "url": { "type": ["string", "null"] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "url", "object", "id"] }, "urlSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "url", "description": "Always `url`" }, "url": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "url"], "title": "Url" }, "userObjectResponse": { "allOf": [ { "$ref": "#/components/schemas/userObjectResponseCommon" }, { "oneOf": [ { "$ref": "#/components/schemas/personUserObjectResponse" }, { "$ref": "#/components/schemas/botUserObjectResponse" } ] } ] }, "userObjectResponseCommon": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the user." }, "object": { "type": "string", "const": "user", "description": "The user object type name." }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the user." }, "avatar_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The avatar URL of the user." } }, "additionalProperties": false, "required": ["id", "object", "name", "avatar_url"] }, "userValueResponse": { "oneOf": [ { "$ref": "#/components/schemas/partialUserObjectResponse" }, { "$ref": "#/components/schemas/userObjectResponse" } ] }, "verificationPropertyItemObjectResponse": { "title": "Verification", "type": "object", "properties": { "type": { "type": "string", "const": "verification" }, "verification": { "anyOf": [ { "$ref": "#/components/schemas/verificationPropertyValueResponse" }, { "type": "null" } ] }, "object": { "type": "string", "const": "property_item" }, "id": { "type": "string" } }, "required": ["type", "verification", "object", "id"] }, "verificationPropertyResponse": { "type": "object", "properties": { "state": { "type": "string", "enum": ["verified", "expired"], "description": "One of: `verified`, `expired`" }, "date": { "oneOf": [ { "$ref": "#/components/schemas/dateResponse" }, { "type": "null" } ] }, "verified_by": { "oneOf": [ { "$ref": "#/components/schemas/userValueResponse" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["state", "date", "verified_by"], "title": "Verified" }, "verificationPropertyUnverifiedResponse": { "type": "object", "properties": { "state": { "type": "string", "const": "unverified", "description": "Always `unverified`" }, "date": { "type": "null" }, "verified_by": { "type": "null" } }, "additionalProperties": false, "required": ["state", "date", "verified_by"], "title": "Unverified" }, "verificationPropertyValueResponse": { "oneOf": [ { "$ref": "#/components/schemas/verificationPropertyUnverifiedResponse" }, { "$ref": "#/components/schemas/verificationPropertyResponse" } ] }, "verificationSimplePropertyValueResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "verification", "description": "Always `verification`" }, "verification": { "oneOf": [ { "$ref": "#/components/schemas/verificationPropertyValueResponse" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["type", "verification"], "title": "Verification" }, "videoBlockObjectResponse": { "title": "Video", "type": "object", "properties": { "type": { "type": "string", "const": "video" }, "video": { "$ref": "#/components/schemas/mediaContentWithFileAndCaptionResponse" }, "parent": { "$ref": "#/components/schemas/parentForBlockBasedObjectResponse" }, "object": { "type": "string", "const": "block" }, "id": { "type": "string", "format": "uuid" }, "created_time": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "last_edited_time": { "type": "string", "format": "date-time" }, "last_edited_by": { "$ref": "#/components/schemas/partialUserObjectResponse" }, "has_children": { "type": "boolean" }, "in_trash": { "type": "boolean" } }, "required": [ "type", "video", "parent", "object", "id", "created_time", "created_by", "last_edited_time", "last_edited_by", "has_children", "in_trash" ] }, "workspaceParentForBlockBasedObjectResponse": { "type": "object", "properties": { "type": { "type": "string", "const": "workspace", "description": "The parent type." }, "workspace": { "type": "boolean", "const": true, "description": "Always true for workspace parent." } }, "additionalProperties": false, "required": ["type", "workspace"] } }, "parameters": { "notionVersion": { "name": "Notion-Version", "in": "header", "required": true, "schema": { "enum": ["2026-03-11"] }, "description": "The [API version](/reference/versioning) to use for this request. The latest version is `2026-03-11`." } } }, "paths": { "/v1/groups/{group_id}/members": { "post": { "summary": "Add a group member", "operationId": "add-group-member", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the group." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "type": { "type": "string", "const": "user", "description": "The type of member." }, "user_id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the user to add." } }, "required": ["type", "user_id"], "description": "The user to add as a direct member." }, "role": { "type": "string", "enum": ["owner", "member"], "description": "The user's role in the group." } }, "required": ["member", "role"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/groupMembershipObjectResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "get": { "summary": "List group members", "operationId": "list-group-members", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the group." } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of items from the full list desired in the response. Maximum: 100" } }, { "name": "start_cursor", "in": "query", "schema": { "type": "string", "description": "If supplied, this endpoint returns a page of results starting after the opaque cursor provided." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "group_membership", "description": "Always `group_membership`" }, "group_membership": { "$ref": "#/components/schemas/emptyObject" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/groupMembershipObjectResponse" }, "maxItems": 100, "description": "The direct user memberships in the group." }, "has_more": { "type": "boolean", "description": "Whether there are more results available." }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor to use for the next page of results, or null if there are no more results." } }, "additionalProperties": false, "required": [ "object", "type", "group_membership", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/external/decagon": { "post": { "summary": "Tools for Decagon's CX chatbot", "operationId": "external-decagon", "security": [ { "basicAuth": [] } ], "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "string", "const": "educationEmailVerification" }, "user_id": { "type": "string" } }, "required": ["tool", "user_id"] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "refundEligibility" }, "space_id": { "type": "string" } }, "required": ["tool", "space_id"] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "getFreeChartsForSpace" }, "space_id": { "type": "string" } }, "required": ["tool", "space_id"] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "optOutNotionAIDataSharing" }, "user_id": { "type": "string" } }, "required": ["tool", "user_id"] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "isWorkspaceDeleted" }, "space_id": { "type": "string" } }, "required": ["tool", "space_id"] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "string", "const": "educationEmailVerification" }, "is_education_email": { "type": "boolean" } }, "required": ["tool", "is_education_email"] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "refundEligibility" }, "subscription_exists": { "type": "boolean", "const": false } }, "required": ["tool", "subscription_exists"] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "refundEligibility" }, "subscription_exists": { "type": "boolean", "const": true }, "is_eligible": { "type": "boolean", "const": true }, "product_name": { "type": "string", "enum": [] }, "invoice_id": { "type": "string" }, "eligible_amount": { "type": "number" }, "eligible_currency": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "tool", "subscription_exists", "is_eligible", "product_name", "invoice_id", "eligible_amount", "eligible_currency", "reason" ] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "refundEligibility" }, "subscription_exists": { "type": "boolean", "const": true }, "is_eligible": { "type": "boolean", "const": false }, "reason": { "type": "string" } }, "required": [ "tool", "subscription_exists", "is_eligible", "reason" ] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "getFreeChartsForSpace" }, "hasFreeChart": { "type": "boolean" }, "spaceCanViewUnlimitedCharts": { "type": "boolean" }, "freeChartIds": { "type": "array", "items": { "type": "string" } }, "freeChartUrls": { "type": "array", "items": { "type": ["string", "null"] } } }, "required": [ "tool", "hasFreeChart", "spaceCanViewUnlimitedCharts", "freeChartIds", "freeChartUrls" ] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "optOutNotionAIDataSharing" }, "success": { "type": "boolean" } }, "required": ["tool", "success"] }, { "type": "object", "properties": { "tool": { "type": "string", "const": "isWorkspaceDeleted" }, "isDeleted": { "type": "boolean" } }, "required": ["tool", "isDeleted"] } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_403" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_500" } } } } } } }, "/v1/external/refundEligibility": { "get": { "summary": "Check if a user is eligible for a refund", "operationId": "external-refund-eligibility", "security": [ { "basicAuth": [] } ], "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "space_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "space_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "subscription_exists": { "type": "boolean", "const": false } }, "required": ["subscription_exists"] }, { "type": "object", "properties": { "subscription_exists": { "type": "boolean", "const": true }, "is_eligible": { "type": "boolean", "const": true }, "product_name": { "type": "string", "enum": [] }, "invoice_id": { "type": "string" }, "eligible_amount": { "type": "number" }, "eligible_currency": { "type": "string" }, "reason": { "type": "string" }, "invoice_generated_date": { "type": "string" } }, "required": [ "subscription_exists", "is_eligible", "product_name", "invoice_id", "eligible_amount", "eligible_currency", "reason", "invoice_generated_date" ] }, { "type": "object", "properties": { "subscription_exists": { "type": "boolean", "const": true }, "is_eligible": { "type": "boolean", "const": false }, "reason": { "type": "string" } }, "required": [ "subscription_exists", "is_eligible", "reason" ] } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_403" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_500" } } } } } } }, "/v1/external/userC360Profile": { "post": { "summary": "Fetch a user's C360 lifecycle signals for Decagon chat init", "operationId": "external-user-c360-profile", "security": [ { "basicAuth": [] } ], "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "epoch": { "type": "number" }, "signature": { "type": "string" } }, "required": ["user_id", "epoch", "signature"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "signals": { "type": "object", "properties": { "sophistication_score": { "type": ["number", "null"] }, "job_seniority": { "type": ["string", "null"] }, "email_type": { "type": ["string", "null"] }, "used_ai_l28": { "type": ["boolean", "null"] }, "has_active_ai_add_on": { "type": ["boolean", "null"] }, "was_w1_wac": { "type": ["boolean", "null"] }, "is_w2_wac": { "type": ["boolean", "null"] }, "was_w2_wac": { "type": ["boolean", "null"] }, "is_l7_active": { "type": ["boolean", "null"] }, "is_l14_active": { "type": ["boolean", "null"] }, "is_l28_active": { "type": ["boolean", "null"] }, "meeting_bucket": { "type": ["string", "null"] }, "meeting_first_usage_date": { "type": ["string", "null"] }, "meeting_n_meetings_recorded": { "type": ["number", "null"] }, "meeting_total_minutes": { "type": ["number", "null"] }, "signup_time": { "type": ["string", "null"] }, "subscription_tier": { "type": ["string", "null"] }, "ai_credit_exhausted": { "type": ["boolean", "null"] }, "l28_ai_agent_active_days": { "type": ["number", "null"] }, "l28_ai_connector_search_active_days": { "type": ["number", "null"] }, "l28_ai_meeting_notes_active_days": { "type": ["number", "null"] }, "l28_collection_creates_days": { "type": ["number", "null"] }, "l28_comments_days": { "type": ["number", "null"] }, "l28_configure_db_view_days": { "type": ["number", "null"] }, "l28_configure_property_days": { "type": ["number", "null"] }, "l28_create_db_property_days": { "type": ["number", "null"] }, "l28_enterprise_ai_search_active_days": { "type": ["number", "null"] }, "l28_filter_or_sort_db_days": { "type": ["number", "null"] }, "l28_page_shares_days": { "type": ["number", "null"] }, "l28_space_invite_days": { "type": ["number", "null"] }, "create_database_l28d": { "type": ["number", "null"] }, "create_database_cumulative": { "type": ["number", "null"] }, "create_relation_l28d": { "type": ["number", "null"] }, "create_property_l28d": { "type": ["number", "null"] }, "content_viewer_count": { "type": ["number", "null"] }, "is_hub_in_any_space": { "type": ["boolean", "null"] }, "approaching_ai_limit_l28": { "type": ["number", "null"] }, "hit_ai_limit_l28": { "type": ["number", "null"] }, "ai_credit_usage": { "type": ["number", "null"] }, "dictation_start_count": { "type": ["number", "null"] } }, "required": [ "sophistication_score", "job_seniority", "email_type", "used_ai_l28", "has_active_ai_add_on", "was_w1_wac", "is_w2_wac", "was_w2_wac", "is_l7_active", "is_l14_active", "is_l28_active", "meeting_bucket", "meeting_first_usage_date", "meeting_n_meetings_recorded", "meeting_total_minutes", "signup_time", "subscription_tier", "ai_credit_exhausted", "l28_ai_agent_active_days", "l28_ai_connector_search_active_days", "l28_ai_meeting_notes_active_days", "l28_collection_creates_days", "l28_comments_days", "l28_configure_db_view_days", "l28_configure_property_days", "l28_create_db_property_days", "l28_enterprise_ai_search_active_days", "l28_filter_or_sort_db_days", "l28_page_shares_days", "l28_space_invite_days", "create_database_l28d", "create_database_cumulative", "create_relation_l28d", "create_property_l28d", "content_viewer_count", "is_hub_in_any_space", "approaching_ai_limit_l28", "hit_ai_limit_l28", "ai_credit_usage", "dictation_start_count" ] }, "request_id": { "type": "string", "format": "uuid" } }, "required": ["signals"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_403" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_500" } } } } } } }, "/v1/sessions/{session_id}/cancel": { "post": { "summary": "Cancel a session", "operationId": "cancel-session", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the session to cancel." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string", "description": "A session event identifying the turn to cancel. If omitted, cancels the current nonterminal turn." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "session", "description": "Always `session`" }, "id": { "type": "string" }, "agent_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ], "description": "One of: `queued`, `in_progress`, `requires_action`, `completed`, `failed`, `canceled`, `terminated`" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "required_actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["approve", "reject"], "description": "One of: `approve`, `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["action_id", "title", "options"] }, "maxItems": 100 }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false, "required": ["code", "message", "retryable"] } }, "additionalProperties": false, "required": [ "object", "id", "agent_id", "title", "status", "created_at", "updated_at" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/agents/{agent_id}/chat": { "post": { "summary": "Chat with agent", "operationId": "chat-with-agent", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent to chat with. Use a UUID for custom agents or `notion_ai` for Notion Agent (personal agent); the reserved UUID `33333333-3333-3333-3333-333333333333` remains supported for backward compatibility." } }, { "name": "verbose", "in": "query", "schema": { "type": "boolean", "description": "Whether to include verbose agent output (thinking, raw tool names, tool calls, and tool results). Defaults to true." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 10000, "description": "The message to send to the agent." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_upload": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of a FileUpload object that has the status `uploaded`." } }, "required": ["id"], "description": "ID of a FileUpload object that has the status `uploaded`." }, "type": { "type": "string", "const": "file_upload", "description": "The type of the attachment. Only supports \"file_upload\"." }, "name": { "type": "string", "description": "An optional display name override for the attachment." } }, "required": ["file_upload"] }, "maxItems": 100, "description": "An array of file uploads to attach to this chat turn. Use the File Upload APIs to create uploads and pass their IDs here." }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "maxLength": 200, "description": "An external user identifier supplied by the API caller for lifecycle metadata and correlation. This does not change the Notion actor used for authorization." } }, "additionalProperties": false, "description": "Optional caller-provided metadata associated with the chat invocation." }, "prompt_context": { "type": "string", "maxLength": 10000, "description": "Additional caller-provided context for the agent to consider while responding." }, "thread_id": { "$ref": "#/components/schemas/idRequest", "description": "Deprecated. Use POST /v1/threads/:thread_id/messages to continue an existing thread. If not provided, a new thread will be created.", "deprecated": true } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat.invocation", "description": "Always `chat.invocation`" }, "agent_id": { "type": "string" }, "thread_id": { "type": "string" }, "invocation_id": { "type": "string" }, "status": { "type": "string", "const": "pending", "description": "Always `pending`" } }, "additionalProperties": false, "required": [ "object", "agent_id", "thread_id", "invocation_id", "status" ] } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON) stream. Each line is a JSON-encoded chat stream chunk." } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "deprecated": true, "x-notion-docs-ref": "https://developers.notion.com/reference/internal/chat-with-agent" } }, "/v1/agents/{agent_id}/chatStream": { "post": { "summary": "Chat with agent (streaming)", "operationId": "chat-with-agent-stream", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent to chat with. Use a UUID for custom agents or `notion_ai` for Notion Agent (personal agent); the reserved UUID `33333333-3333-3333-3333-333333333333` remains supported for backward compatibility." } }, { "name": "verbose", "in": "query", "schema": { "type": "boolean", "description": "Whether to include verbose agent output (thinking, raw tool names, tool calls, and tool results). Defaults to true." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 10000, "description": "The message to send to the agent." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_upload": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of a FileUpload object that has the status `uploaded`." } }, "required": ["id"], "description": "ID of a FileUpload object that has the status `uploaded`." }, "type": { "type": "string", "const": "file_upload", "description": "The type of the attachment. Only supports \"file_upload\"." }, "name": { "type": "string", "description": "An optional display name override for the attachment." } }, "required": ["file_upload"] }, "maxItems": 100, "description": "An array of file uploads to attach to this chat turn. Use the File Upload APIs to create uploads and pass their IDs here." }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "maxLength": 200, "description": "An external user identifier supplied by the API caller for lifecycle metadata and correlation. This does not change the Notion actor used for authorization." } }, "additionalProperties": false, "description": "Optional caller-provided metadata associated with the chat invocation." }, "prompt_context": { "type": "string", "maxLength": 10000, "description": "Additional caller-provided context for the agent to consider while responding." }, "thread_id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of an existing thread to continue the conversation. If not provided, a new thread will be created." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "message", "description": "Always `message`" }, "invocation_id": { "type": "string" }, "id": { "$ref": "#/components/schemas/idResponse" }, "role": { "type": "string", "enum": ["user", "agent"], "description": "One of: `user`, `agent`" }, "content": { "type": "string" }, "delta": { "type": "string", "description": "Text appended since the previous chunk for this message. Empty for metadata-only updates. If previously emitted text is revised, this contains the full current text. The cumulative `content` field remains authoritative." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "content_type": { "type": "string" }, "url": { "type": "string" }, "expiry_time": { "type": "string", "format": "date-time", "description": "The time when the attachment URL will expire." } }, "additionalProperties": false, "required": ["name", "content_type", "url"] }, "maxItems": 100 }, "content_parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Always `text`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "thinking", "description": "Always `thinking`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "tool_call", "description": "Always `tool_call`" }, "tool_call_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_name": { "type": "string" }, "input": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "agent_step_id": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "tool_call_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_name": { "type": "string" }, "tool_type": { "type": "string" }, "state": { "type": "string" }, "input": { "oneOf": [ {}, { "type": "null" } ] }, "output": { "oneOf": [ {}, { "type": "null" } ] }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "started_at": { "type": "integer", "minimum": 0 }, "finished_at": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "duration_ms": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "id", "agent_step_id", "tool_call_id", "tool_name", "tool_type", "state", "input", "output", "error", "started_at", "finished_at", "duration_ms" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "tool_call_id", "tool_name", "input" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "follow_ups", "description": "Always `follow_ups`" }, "follow_ups": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false, "required": ["label", "message"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "follow_ups"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_agent_template_picker", "description": "Always `custom_agent_template_picker`" } }, "additionalProperties": false, "required": ["type"] } ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "invocation_id", "id", "role", "content", "delta" ], "title": "Message" }, { "type": "object", "properties": { "type": { "type": "string", "const": "tool", "description": "Always `tool`" }, "invocation_id": { "type": "string" }, "id": { "$ref": "#/components/schemas/idResponse" }, "category": { "type": "string", "enum": [ "search", "read", "write", "compute", "other" ], "description": "Stable, coarse category suitable for displaying progress without exposing internal tool details." }, "status": { "type": "string", "enum": [ "pending", "running", "waiting_for_user", "completed", "failed" ], "description": "One of: `pending`, `running`, `waiting_for_user`, `completed`, `failed`" }, "agent_step_id": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "tool_call_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_name": { "type": "string" }, "tool_type": { "type": "string" }, "input": {} }, "additionalProperties": false, "required": [ "type", "invocation_id", "id", "category", "status" ], "title": "Tool" }, { "type": "object", "properties": { "type": { "type": "string", "const": "started", "description": "Always `started`" }, "invocation_id": { "type": "string" }, "thread_id": { "$ref": "#/components/schemas/idResponse" }, "agent_id": { "type": "string", "description": "Agent identifier echoed from the request path. May be a UUID with or without dashes." }, "model": { "type": "string", "description": "Configured model identifier, or `auto` when model routing has not resolved yet." }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "description": "External user identifier supplied by the API caller in request metadata." } }, "additionalProperties": false, "title": "ChatLifecycleMetadata", "description": "Caller-provided lifecycle metadata echoed from the chat request." } }, "additionalProperties": false, "required": [ "type", "invocation_id", "thread_id", "agent_id", "model" ], "title": "Started" }, { "type": "object", "properties": { "type": { "type": "string", "const": "done", "description": "Always `done`" }, "invocation_id": { "type": "string" }, "status": { "type": "string", "enum": ["completed", "requires_action", "canceled"], "description": "One of: `completed`, `requires_action`, `canceled`" }, "thread_id": { "$ref": "#/components/schemas/idResponse" }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "total_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": ["total_tokens"] }, "duration_ms": { "type": "integer", "minimum": 0 }, "connections_used": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "artifacts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "url": { "type": "string" }, "title": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url", "title"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "html_artifact", "description": "Always `html_artifact`" }, "url": { "type": "string" }, "page_url": { "type": "string" } }, "additionalProperties": false, "required": ["type", "url", "page_url"] } ], "title": "Chat stream artifact" }, "maxItems": 100 }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "description": "External user identifier supplied by the API caller in request metadata." } }, "additionalProperties": false, "title": "ChatLifecycleMetadata", "description": "Caller-provided lifecycle metadata echoed from the chat request." }, "pending_user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "type": { "type": "string", "const": "tool_confirmation", "description": "Always `tool_confirmation`" }, "title": { "type": "string" }, "requirements": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "general", "description": "Always `general`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "manage_workers", "description": "Always `manage_workers`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "url_safety", "description": "Always `url_safety`" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "required_by_workspace_policy": { "type": "boolean" } }, "additionalProperties": false, "required": ["type", "urls"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "permission_escalation", "description": "Always `permission_escalation`" }, "destination_title": { "type": "string" }, "source_titles": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "delete_content", "description": "Always `delete_content`" }, "page_count": { "type": "integer", "minimum": 0 }, "database_count": { "type": "integer", "minimum": 0 }, "meeting_notes_block_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "type", "page_count", "database_count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "connect_integration", "description": "Always `connect_integration`" }, "integration_type": { "type": "string" }, "integration_name": { "type": "string" }, "handoff_url": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "integration_type", "integration_name", "handoff_url" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_mode", "description": "Always `admin_mode`" }, "explanation": { "type": "string" } }, "additionalProperties": false, "required": ["type"] } ], "title": "Pending user action requirement" }, "maxItems": 100 }, "options": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "const": "approve", "description": "Always `approve`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "reject", "description": "Always `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "use_connection", "description": "Always `use_connection`" }, "label": { "type": "string" }, "input": { "type": "object", "properties": { "type": { "type": "string", "const": "connection_id", "description": "Always `connection_id`" }, "required": { "type": "boolean", "const": true, "description": "Always `true`" } }, "additionalProperties": false, "required": ["type", "required"] } }, "additionalProperties": false, "required": ["id", "label", "input"] } ], "title": "Pending user action option" }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "id", "type", "title", "requirements", "options" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "invocation_id", "status", "thread_id", "model", "usage", "duration_ms", "connections_used", "artifacts" ], "title": "Done" }, { "type": "object", "properties": { "type": { "type": "string", "const": "waiting_for_user", "description": "Always `waiting_for_user`" }, "invocation_id": { "type": "string" }, "pending_user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "type": { "type": "string", "const": "tool_confirmation", "description": "Always `tool_confirmation`" }, "title": { "type": "string" }, "requirements": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "general", "description": "Always `general`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "manage_workers", "description": "Always `manage_workers`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "url_safety", "description": "Always `url_safety`" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "required_by_workspace_policy": { "type": "boolean" } }, "additionalProperties": false, "required": ["type", "urls"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "permission_escalation", "description": "Always `permission_escalation`" }, "destination_title": { "type": "string" }, "source_titles": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "delete_content", "description": "Always `delete_content`" }, "page_count": { "type": "integer", "minimum": 0 }, "database_count": { "type": "integer", "minimum": 0 }, "meeting_notes_block_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "type", "page_count", "database_count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "connect_integration", "description": "Always `connect_integration`" }, "integration_type": { "type": "string" }, "integration_name": { "type": "string" }, "handoff_url": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "integration_type", "integration_name", "handoff_url" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_mode", "description": "Always `admin_mode`" }, "explanation": { "type": "string" } }, "additionalProperties": false, "required": ["type"] } ], "title": "Pending user action requirement" }, "maxItems": 100 }, "options": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "const": "approve", "description": "Always `approve`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "reject", "description": "Always `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "use_connection", "description": "Always `use_connection`" }, "label": { "type": "string" }, "input": { "type": "object", "properties": { "type": { "type": "string", "const": "connection_id", "description": "Always `connection_id`" }, "required": { "type": "boolean", "const": true, "description": "Always `true`" } }, "additionalProperties": false, "required": ["type", "required"] } }, "additionalProperties": false, "required": ["id", "label", "input"] } ], "title": "Pending user action option" }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "id", "type", "title", "requirements", "options" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "invocation_id", "pending_user_actions" ], "title": "Waiting for user" }, { "type": "object", "properties": { "type": { "type": "string", "const": "error", "description": "Always `error`" }, "code": { "type": "string", "enum": [ "invalid_json", "invalid_request_url", "invalid_request", "missing_version", "invalid_beta", "validation_error", "unauthorized", "restricted_resource", "object_not_found", "directory_not_found", "rate_limited", "service_overload", "internal_server_error", "service_unavailable", "gateway_timeout", "conflict_error", "row_limit_exceeded", "status_change_not_allowed", "agent_deleted", "invalid_credit_limit", "workspace_credits_exhausted", "agent_credit_limit_reached" ], "description": "Programmatic error code. Matches the error codes used by non-streaming Public API endpoints." }, "message": { "type": "string" }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 } ] } }, "invocation_id": { "type": "string", "description": "Present after the invocation is accepted; absent for pre-acceptance errors." }, "usage": { "type": "object", "properties": { "total_tokens": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": ["total_tokens"] } }, "additionalProperties": false, "required": ["type", "code", "message"], "title": "Error" } ], "title": "Chat stream chunk", "description": "A single NDJSON chunk from the chat streaming response. Each line in the stream is one of these chunk types." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON) stream. Each line is a JSON-encoded chunk object." } } } } }, "deprecated": true, "x-notion-docs-ref": "https://developers.notion.com/reference/internal/chat-with-agent-stream" } }, "/v1/threads/{thread_id}/continue": { "post": { "summary": "Continue a thread", "operationId": "continue-thread", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the thread." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action_id": { "$ref": "#/components/schemas/idRequest" }, "option_id": { "type": "string", "enum": ["approve", "reject"], "description": "One of: `approve`, `reject`" } }, "additionalProperties": false, "required": ["action_id", "option_id"] }, { "type": "object", "properties": { "action_id": { "$ref": "#/components/schemas/idRequest" }, "option_id": { "type": "string", "const": "use_connection", "description": "Always `use_connection`" }, "input": { "type": "object", "properties": { "connection_id": { "$ref": "#/components/schemas/idRequest" } }, "additionalProperties": false, "required": ["connection_id"] } }, "additionalProperties": false, "required": ["action_id", "option_id", "input"] } ], "title": "Continue thread request", "description": "A response to one pending user action." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat.invocation", "description": "Always `chat.invocation`" }, "agent_id": { "type": "string" }, "thread_id": { "type": "string" }, "invocation_id": { "type": "string" }, "status": { "type": "string", "const": "pending", "description": "Always `pending`" } }, "additionalProperties": false, "required": [ "object", "agent_id", "thread_id", "invocation_id", "status" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "deprecated": true } }, "/v1/external_agent_stub/{agent_id}/vaults": { "post": { "summary": "Create external agent stub vault", "operationId": "create-external-agent-stub-vault", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "33333333-3333-3333-3333-333333333333", "description": "Always `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent backing this external agent session." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200, "description": "Provider-defined vault name." }, "credential": { "type": "object", "properties": { "value": { "type": "string", "description": "Write-only bearer credential." }, "expires_at": { "type": "string", "maxLength": 100, "description": "Credential expiry as an RFC 3339 instant." } }, "required": ["value", "expires_at"], "description": "Write-only credential input." }, "target": { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "MCP server target." }, "server_url": { "type": "string", "maxLength": 2000, "description": "The exact target server URL." }, "authorization": { "type": "object", "properties": { "type": { "type": "string", "const": "bearer", "description": "Bearer authorization." } }, "required": ["type"], "description": "Target authorization metadata." } }, "required": ["type", "server_url", "authorization"], "description": "Credential target." } }, "required": ["name", "credential", "target"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "credential": { "type": "object", "properties": { "expires_at": { "type": "string" } }, "additionalProperties": false, "required": ["expires_at"] }, "target": { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_url": { "type": "string" }, "authorization": { "type": "object", "properties": { "type": { "type": "string", "const": "bearer", "description": "Always `bearer`" } }, "additionalProperties": false, "required": ["type"] } }, "additionalProperties": false, "required": ["type", "server_url", "authorization"] }, "status": { "type": "string", "enum": ["active", "expired"], "description": "One of: `active`, `expired`" }, "version": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false, "required": [ "id", "name", "credential", "target", "status", "version", "created_at", "updated_at" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/groups": { "post": { "summary": "Create a group", "operationId": "create-group", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S", "examples": ["Engineering"], "description": "The name of the group." } }, "required": ["name"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/permissionGroupObjectResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/rollout": { "post": { "summary": "Create a rollout", "operationId": "create-rollout", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["execution"], "properties": { "json": { "description": "Inline rollout JSON payload." }, "braintrustSlug": { "type": "string", "description": "Braintrust source in 'project:dataset:rowId' or 'org:project:dataset:rowId' format." }, "braintrust": { "type": "object", "additionalProperties": true, "properties": { "org": { "type": "string" }, "project": { "type": "string" }, "dataset": { "type": "string" }, "id": { "type": "string" }, "logId": { "type": "string" } } }, "preprocessors": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "response": { "type": "object", "properties": { "input": { "type": "boolean", "description": "Whether to include the original input in the response payload. Defaults to false." }, "originalMetadata": { "type": "boolean", "description": "Whether to include source scenario metadata under metadata.originalMetadata. Defaults to false." } } }, "execution": { "type": "object", "properties": { "agentRunner": { "type": "object", "additionalProperties": true, "properties": { "evalMode": { "type": "string", "enum": ["live", "sandbox", "single-step"] }, "workflowAgentMode": { "type": "string", "enum": ["basic", "all"] }, "startFromLastStepOfType": { "type": "string" }, "contextPageId": { "type": "string" }, "additionalDebugOverrides": { "type": "object", "additionalProperties": true }, "agentModelConfig": { "type": "object", "additionalProperties": true }, "subagentModelConfig": { "type": "object", "additionalProperties": true } } }, "modelConfig": { "type": "object", "additionalProperties": true, "properties": { "notionModelName": { "type": "string" }, "rawVendorOverride": { "type": "object", "additionalProperties": true } } }, "appEnvironment": { "type": "object", "additionalProperties": true, "properties": { "actorId": { "type": "string" }, "createThread": { "type": "boolean" }, "attachmentUrlResolver": { "type": "string", "enum": ["admin", "thread"] } } }, "outputProcessors": { "type": "array", "items": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["formatted"] } } } }, "logging": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["includeRawInferences"] } } }, { "type": "object", "required": ["type", "enabled"], "properties": { "type": { "type": "string", "enum": ["braintrustLogs"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } } } ] } } } } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "rolloutId": { "type": "string", "description": "Identifier for the rollout. Input and output payloads are stored in AI logging S3, and rollouts are readable for up to 7 days." } }, "additionalProperties": false, "required": ["rolloutId"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/teamspaces": { "post": { "summary": "Create teamspace", "operationId": "create-teamspace", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "examples": ["Engineering Team"], "description": "The name of the teamspace to create." }, "visibility": { "type": "string", "enum": ["default", "open", "closed", "private"], "description": "The teamspace's visibility in the workspace. Options include: default, open, closed, private." }, "description": { "type": "string", "examples": ["Team for engineering projects"], "description": "The description for the teamspace." }, "icon": { "$ref": "#/components/schemas/pageIconRequest", "description": "The icon for the teamspace." }, "settings": { "type": "object", "properties": { "allow_members_to_invite_members": { "type": "boolean", "description": "When true, members can invite other members. When false, only teamspace owners can. Corresponds to the 'Who can invite or remove teamspace members` setting." }, "allow_members_to_change_sidebar": { "type": "boolean", "description": "When true, members can edit the sidebar. When false, only teamspace owners can. Corresponds to the `Who can edit teamspace sidebar` setting." }, "disable_invite_link": { "type": "boolean", "description": "When true, invite links are disabled. Corresponds to the `Invite Link` toggle." }, "disable_public_pages": { "type": "boolean", "description": "When true, public pages are disabled. Corresponds to the `Disable publishing sites, forms, and public links` toggle." }, "disable_guests": { "type": "boolean", "description": "When true, guests are disabled and removed from the teamspace. Corresponds to the `Disable guests` toggle." }, "disable_restricted_members": { "type": "boolean", "description": "When true, restricted members are disabled and removed from the teamspace. Corresponds to the `Disable restricted members` toggle." }, "disable_export": { "type": "boolean", "description": "When true, exporting pages is disabled. Corresponds to the `Disable export` toggle." } }, "description": "The settings of the teamspace." } }, "required": ["name", "visibility"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "teamspace", "description": "The team object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the teamspace." }, "name": { "type": "string", "description": "The name of the teamspace." }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The description of the teamspace." }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "null" } ], "description": "The icon of the teamspace." }, "in_trash": { "type": "boolean", "description": "Whether the teamspace is in the trash." }, "visibility": { "type": "string", "enum": ["default", "open", "closed", "private"], "description": "The teamspace's visibility in the workspace." }, "settings": { "oneOf": [ { "type": "object", "properties": { "allow_members_to_invite_members": { "type": "boolean", "description": "Whether members can invite other members." }, "allow_members_to_change_sidebar": { "type": "boolean", "description": "Whether members can change the sidebar." }, "disable_invite_link": { "type": "boolean", "description": "Whether invite links are allowed." }, "disable_public_pages": { "type": "boolean", "description": "Whether public pages are allowed." }, "disable_guests": { "type": "boolean", "description": "Whether guests are allowed." }, "disable_restricted_members": { "type": "boolean", "description": "Whether restricted members are allowed." }, "disable_export": { "type": "boolean", "description": "Whether export is allowed." } }, "additionalProperties": false, "required": [ "allow_members_to_invite_members", "allow_members_to_change_sidebar", "disable_invite_link", "disable_public_pages", "disable_guests", "disable_restricted_members", "disable_export" ] }, { "type": "null" } ], "description": "The teamspace's settings." } }, "additionalProperties": false, "required": [ "object", "id", "name", "description", "icon", "in_trash", "visibility", "settings" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "get": { "summary": "List teamspaces", "operationId": "list-teamspaces", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "start_cursor", "in": "query", "schema": { "type": "string", "description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results." } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "description": "Number of teamspaces desired in the response." } }, { "name": "user_id", "in": "query", "schema": { "$ref": "#/components/schemas/idRequest", "description": "If provided, returns the teamspaces that the given user can access." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "next_cursor": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "has_more": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "teamspace", "description": "The teamspace object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the teamspace." }, "teamspace_name": { "type": "string", "description": "The name of the teamspace." } }, "additionalProperties": false, "required": ["object", "id", "teamspace_name"] } }, "type": { "type": "string", "const": "teamspace", "description": "Always `teamspace`" }, "teamspace": { "$ref": "#/components/schemas/emptyObject" }, "request_status": { "$ref": "#/components/schemas/requestStatusResponse" } }, "required": [ "object", "next_cursor", "has_more", "results", "type", "teamspace" ], "additionalProperties": false } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/agents/{agent_id}": { "delete": { "summary": "Delete agent", "operationId": "delete-agent", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The agent ID (a UUID), or `notion_ai` for the personal agent. The personal agent cannot be deleted." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "$ref": "#/components/schemas/idResponse" }, "status": { "type": "string", "const": "deleted", "description": "Always \"deleted\": the agent has been soft-deleted (recoverable)." }, "deleted_at": { "type": "string", "description": "ISO 8601 timestamp of when the agent was deleted." } }, "additionalProperties": false, "required": ["agent_id", "status", "deleted_at"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "get": { "summary": "Get agent", "operationId": "get-agent", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply." } }, { "name": "verbose", "in": "query", "schema": { "type": "boolean", "description": "Whether to include the agent's inline instructions. Defaults to false." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "agent", "description": "Always `agent`" }, "id": { "$ref": "#/components/schemas/idResponse" }, "agent_type": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent", "external" ], "description": "What kind of agent this is: \"notion_ai\" is the personal agent; \"custom_agent\" is a standalone agent you chat with; \"autofill_custom_agent\" fills a database property; \"external\" runs through an external provider." }, "name": { "type": "string" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "instructions_page_id": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_agent_avatar", "description": "Type of icon. In this case, a custom agent avatar." }, "custom_agent_avatar": { "type": "object", "properties": { "static_url": { "type": "string", "description": "The URL of the static custom agent avatar." }, "animated_url": { "type": "string", "description": "The URL of the animated custom agent avatar." } }, "additionalProperties": false, "required": ["static_url", "animated_url"], "description": "The static and animated URLs for the agent avatar." } }, "additionalProperties": false, "required": ["type", "custom_agent_avatar"] }, { "type": "null" } ] }, "model": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "auto", "description": "Always `auto`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "pinned", "description": "Always `pinned`" }, "id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The public model this agent maps to (e.g. \"claude-sonnet-5\"), or null for a pre-release / early-access model." } }, "additionalProperties": false, "required": ["type", "id"] } ], "description": "The model the agent runs on: auto (Notion selects) or a pinned model." }, "connections": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "notion", "description": "Always `notion`" }, "name": { "type": "string" }, "account": { "type": "null" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "database_property", "description": "Always `database_property`" }, "data_source_id": { "type": "string" }, "property_id": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "data_source_id", "property_id" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "agent", "description": "Always `agent`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "workspace", "description": "Always `workspace`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "owner_private_pages", "description": "Always `owner_private_pages`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "web_search", "description": "Always `web_search`" }, "allowed_domains": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Domains web search is restricted to, or null when unrestricted." } }, "additionalProperties": false, "required": [ "type", "allowed_domains" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "notion_help_docs_search", "description": "Always `notion_help_docs_search`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Content roles (\"reader\" | \"comment_only\" | \"read_and_write\" | \"editor\") for scoped targets, or search verbs (\"allow\" | \"disallow\") for the search targets." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack", "description": "Always `slack`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "slack_workspace", "description": "Always `slack_workspace`" }, "team_id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "team_id"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The linked Slack workspace, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "slack_channel", "description": "Always `slack_channel`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack_all_public_channels", "description": "Always `slack_all_public_channels`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack_all_channels", "description": "Always `slack_all_channels`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Slack verbs granted on this target (\"read\" | \"write\" | \"reply_in_thread\" | \"react\")." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "discord", "description": "Always `discord`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "discord_server", "description": "Always `discord_server`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The linked Discord server, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "discord_channel", "description": "Always `discord_channel`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "discord_all_channels", "description": "Always `discord_all_channels`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Discord verbs granted on this target (\"read\" | \"write\" | \"reply_in_thread\" | \"react\")." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_host": { "type": "string", "description": "The MCP server host (never the full URL, which can carry credentials or private path components)." } }, "additionalProperties": false, "required": ["type", "server_host"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The MCP server host, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "enabled_tools": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["name", "title"] }, "maxItems": 100 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The tools the agent may call, null when all tools are enabled (including any the server adds later), or \"hidden\" when the caller lacks edit access to the agent." }, "run_tools_automatically": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Whether read tool calls run without a confirmation step." }, "write": { "type": "boolean", "description": "Whether write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": ["read", "write"], "description": "Whether read / write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": [ "type", "name", "account", "enabled_tools", "run_tools_automatically" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_mcp_server", "description": "Always `custom_mcp_server`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_host": { "type": "string", "description": "The MCP server host (never the full URL, which can carry credentials or private path components)." } }, "additionalProperties": false, "required": ["type", "server_host"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The MCP server host, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "enabled_tools": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["name", "title"] }, "maxItems": 100 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The tools the agent may call, null when all tools are enabled (including any the server adds later), or \"hidden\" when the caller lacks edit access to the agent." }, "run_tools_automatically": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Whether read tool calls run without a confirmation step." }, "write": { "type": "boolean", "description": "Whether write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": ["read", "write"], "description": "Whether read / write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": [ "type", "name", "account", "enabled_tools", "run_tools_automatically" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana", "box", "browser", "calendar", "computer", "confluence", "cursor", "files", "fs", "github", "gmail", "google_calendar", "google_drive", "google_drive_oauth", "gtm", "helpdocs", "images", "jira", "linear", "mail", "marketplace", "memory", "microsoft_teams", "outlook", "salesforce", "search", "security", "sharepoint", "skills", "system", "test", "web", "webhooks", "worker", "workers" ], "description": "The connector's machine name (e.g. \"github\", \"google_drive\")." }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider-side account identifier, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "The scopes granted on this target." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] } ] }, "maxItems": 100, "description": "Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions." }, "status": { "type": "string", "enum": ["active", "disabled", "deleted"], "description": "\"active\" when the agent can run; \"disabled\" when it is paused (see pause_reason); \"deleted\" when it has been removed." }, "pause_reason": { "oneOf": [ { "type": "string", "enum": [ "run_limit", "credit_limit", "runaway_credit_usage", "workspace_credit_limit", "failure_limit", "mark_session_failed_autopause", "disabled_from_workspace_settings", "disabled_from_api", "disabled_from_agent_settings", "disabled_due_to_no_members_with_access", "disabled_due_to_lack_of_editors", "disabled_by_notion", "internal_error", "needs_user_review", "tool_unavailable" ], "description": "One of: `run_limit`, `credit_limit`, `runaway_credit_usage`, `workspace_credit_limit`, `failure_limit`, `mark_session_failed_autopause`, `disabled_from_workspace_settings`, `disabled_from_api`, `disabled_from_agent_settings`, `disabled_due_to_no_members_with_access`, `disabled_due_to_lack_of_editors`, `disabled_by_notion`, `internal_error`, `needs_user_review`, `tool_unavailable`" }, { "type": "null" } ], "description": "Why the agent is paused when status is \"disabled\" (e.g. \"credit_limit\", \"disabled_from_workspace_settings\"); null when active." }, "created_by": { "oneOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "user", "description": "Always `user`" }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the user that created this agent." } }, "additionalProperties": false, "required": ["object", "id"] }, { "type": "null" } ] }, "version": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the published artifact." }, "number": { "type": "number", "description": "The version number." }, "published_at": { "type": "string", "description": "The ISO 8601 timestamp when this version was published." } }, "additionalProperties": false, "required": ["id", "number", "published_at"] }, { "type": "null" } ] }, "has_unpublished_changes": { "oneOf": [ { "type": "boolean" }, { "type": "string", "const": "hidden", "description": "Always `hidden`" } ], "description": "Whether the draft has edits not yet in the published version, or \"hidden\" when the caller lacks edit access to the agent." }, "last_run_time": { "oneOf": [ { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T" }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the agent's most recent run, null if it has never run, or \"hidden\" when the caller lacks edit access to the agent." }, "credit_limit": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The per-agent credit limit that applies to this agent, null when uncapped, or \"hidden\" when the caller lacks full access to the agent. This is the effective limit computed at runtime, folding in both the agent's own limit and any workspace-admin default." }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine trigger type (e.g. \"notion.agent.mentioned\", \"recurrence\", \"slack.reaction.added\")." }, "enabled": { "type": "boolean", "description": "Whether this trigger is currently enabled." }, "schedule": { "type": "object", "properties": { "frequency": { "type": "string", "description": "Base cadence unit (\"hour\" | \"day\" | \"week\" | \"month\" | \"year\")." }, "interval": { "type": "integer", "minimum": 1, "description": "Multiplier on the frequency (e.g. every 2 weeks)." }, "weekdays": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Days of the week the schedule runs (e.g. \"monday\"). Present for weekly cadences and monthly weekday restrictions." }, "monthdays": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 100, "description": "Days of the month the schedule runs. Present for monthly monthday restrictions." }, "week_numbers": { "type": "array", "items": { "type": "integer" }, "maxItems": 100, "description": "Week-of-month ordinals for a monthly weekday restriction (e.g. [2, 3] for the 2nd and 3rd occurrence); -1 means the last week." }, "hour": { "type": "integer", "minimum": 0, "description": "Hour of day (0–23) the schedule runs." }, "minute": { "type": "integer", "minimum": 0, "description": "Minute of the hour (0–59) the schedule runs." }, "timezone": { "type": "string", "description": "IANA timezone (e.g. \"America/New_York\")." }, "start_date": { "type": "string", "description": "ISO 8601 timestamp the schedule starts from." }, "end": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "end_at": { "type": "string", "description": "ISO 8601 timestamp when the schedule stops." } }, "additionalProperties": false, "required": ["type", "end_at"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "count", "description": "Always `count`" }, "occurrences": { "type": "integer", "minimum": 0, "description": "Number of occurrences after which the schedule stops." } }, "additionalProperties": false, "required": ["type", "occurrences"] } ], "description": "When the schedule stops, when it is bounded." } }, "additionalProperties": false, "required": ["frequency", "interval"], "description": "Structured recurrence cadence. Present only for recurrence triggers." }, "config": { "type": "object", "additionalProperties": {}, "description": "Remaining per-type trigger configuration (e.g. watched channel ids, reaction config), keys in snake_case. Present only when the trigger carries such state." } }, "additionalProperties": false, "required": ["type", "enabled"] }, "maxItems": 100, "description": "The agent's configured triggers, each with a machine type, an enabled flag, and (for recurrence triggers) a structured schedule." }, "created_time": { "type": "string", "format": "date-time", "description": "Date and time when this agent was created." }, "last_edited_time": { "type": "string", "format": "date-time", "description": "Date and time when this agent was last edited." }, "instructions": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's inline instructions when verbose=true, or null when its instructions are stored on a page." } }, "additionalProperties": false, "required": [ "object", "id", "agent_type", "name", "description", "instructions_page_id", "icon", "model", "connections", "status", "pause_reason", "created_by", "version", "has_unpublished_changes", "last_run_time", "credit_limit", "triggers" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/external_agent_stub/{agent_id}/vaults/{vault_id}": { "delete": { "summary": "Delete external agent stub vault", "operationId": "delete-external-agent-stub-vault", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "33333333-3333-3333-3333-333333333333", "description": "Always `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent backing this external agent session." } }, { "name": "vault_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200, "description": "The provider-owned vault ID." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/emptyObject" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "patch": { "summary": "Update external agent stub vault", "operationId": "update-external-agent-stub-vault", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "33333333-3333-3333-3333-333333333333", "description": "Always `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent backing this external agent session." } }, { "name": "vault_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200, "description": "The provider-owned vault ID." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 1, "maximum": 9007199254740990, "description": "The last observed vault version." }, "credential": { "type": "object", "properties": { "value": { "type": "string", "description": "Write-only bearer credential." }, "expires_at": { "type": "string", "maxLength": 100, "description": "Credential expiry as an RFC 3339 instant." } }, "required": ["value", "expires_at"], "description": "Replacement write-only credential." } }, "required": ["expected_version", "credential"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "credential": { "type": "object", "properties": { "expires_at": { "type": "string" } }, "additionalProperties": false, "required": ["expires_at"] }, "target": { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_url": { "type": "string" }, "authorization": { "type": "object", "properties": { "type": { "type": "string", "const": "bearer", "description": "Always `bearer`" } }, "additionalProperties": false, "required": ["type"] } }, "additionalProperties": false, "required": ["type", "server_url", "authorization"] }, "status": { "type": "string", "enum": ["active", "expired"], "description": "One of: `active`, `expired`" }, "version": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false, "required": [ "id", "name", "credential", "target", "status", "version", "created_at", "updated_at" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/groups/{group_id}": { "delete": { "summary": "Delete a group", "operationId": "delete-group", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the group." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer_to_owner_id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of an active workspace owner who will receive access that would otherwise be orphaned." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/permissionGroupObjectResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "get": { "summary": "Retrieve a group", "operationId": "retrieve-group", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the group." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/permissionGroupObjectResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "patch": { "summary": "Update a group", "operationId": "update-group", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the group." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S", "examples": ["Engineering"], "description": "The new name of the group." } }, "required": ["name"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/permissionGroupObjectResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/export/{id}": { "get": { "summary": "Export a page", "operationId": "export-page", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the page or block to export." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "export", "description": "The type of object, always 'export'." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the exported page or block." }, "pdf_export_url": { "type": "string", "description": "URL to download the page export (PDF)." }, "metadata_export_url": { "type": "string", "description": "URL to download the metadata export (JSON)." }, "comments_export_url": { "type": "string", "description": "URL to download the comments export (JSON)." }, "attachments_export_url": { "type": "string", "description": "URL to download the attachments export (JSON)." }, "permissions_export_url": { "type": "string", "description": "URL to download the permissions export (JSON)." } }, "additionalProperties": false, "required": [ "object", "id", "pdf_export_url", "metadata_export_url", "comments_export_url", "attachments_export_url", "permissions_export_url" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/rollout/generate-transcript": { "post": { "summary": "Generate transcript", "operationId": "generate-transcript", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Discriminated by `kind`. Selects which initial step opens the assembled transcript.", "discriminator": { "propertyName": "kind" }, "oneOf": [ { "type": "object", "required": ["kind", "prompt", "actorId"], "properties": { "kind": { "type": "string", "enum": ["user-input"] }, "prompt": { "type": "string", "description": "Free-text prompt to run as a fresh user-input agent request." }, "workflowId": { "type": "string", "description": "Optional custom-agent workflow ID. Omit to target the personal agent." }, "currentPageId": { "type": "string", "description": "Optional page block ID the user is viewing when invoking the agent." }, "actorId": { "type": "string", "description": "Notion user ID to use as the transcript actor. Must be a member of the API token's workspace." }, "promptFormat": { "type": "string", "enum": ["markdownVNext", "plainText"], "description": "How `prompt` is interpreted. `markdownVNext` (default) parses Notion Markdown vNext into a mention-bearing user step; `plainText` uses the prompt verbatim." } }, "additionalProperties": true }, { "type": "object", "required": [ "kind", "workflowId", "triggerId", "triggerData" ], "properties": { "kind": { "type": "string", "enum": ["agent-trigger"] }, "workflowId": { "type": "string", "description": "Custom-agent workflow ID." }, "triggerId": { "type": "string", "description": "ID of a trigger defined on the target workflow. The server uses it to derive the step's triggerType - a value that doesn't match any real trigger will be rejected." }, "triggerData": { "type": "object", "additionalProperties": true, "description": "Synthetic trigger event payload. Shape must match the trigger type's expected variables (e.g. for a calendar trigger, supply calendar event fields)." } }, "additionalProperties": true } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "transcript": { "type": "array", "items": {}, "maxItems": 100, "description": "The assembled inference transcript (config + context + initial step) that would be sent to the model for this request. Suitable for use as eval input." } }, "additionalProperties": false, "required": ["transcript"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/agents/{agent_id}/insights": { "get": { "summary": "Get agent insights", "operationId": "get-agent-insights", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply." } }, { "name": "start_time", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Start of the insights window, as an epoch timestamp in seconds. Must be supplied together with `end_time`; if either is omitted the window defaults to the current billing period." } }, { "name": "end_time", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "End of the insights window, as an epoch timestamp in seconds. Must be supplied together with `start_time`; if either is omitted the window defaults to the current billing period." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "agent_insights", "description": "Always `agent_insights`" }, "id": { "$ref": "#/components/schemas/idResponse" }, "name": { "type": "string" }, "agent_type": { "type": "string", "enum": ["custom_agent", "autofill_custom_agent"], "description": "One of: `custom_agent`, `autofill_custom_agent`" }, "status": { "type": "string", "enum": ["active", "disabled", "deleted"], "description": "One of: `active`, `disabled`, `deleted`" }, "pause_reason": { "oneOf": [ { "type": "string", "enum": [ "run_limit", "credit_limit", "runaway_credit_usage", "workspace_credit_limit", "failure_limit", "mark_session_failed_autopause", "disabled_from_workspace_settings", "disabled_from_api", "disabled_from_agent_settings", "disabled_due_to_no_members_with_access", "disabled_due_to_lack_of_editors", "disabled_by_notion", "internal_error", "needs_user_review", "tool_unavailable" ], "description": "One of: `run_limit`, `credit_limit`, `runaway_credit_usage`, `workspace_credit_limit`, `failure_limit`, `mark_session_failed_autopause`, `disabled_from_workspace_settings`, `disabled_from_api`, `disabled_from_agent_settings`, `disabled_due_to_no_members_with_access`, `disabled_due_to_lack_of_editors`, `disabled_by_notion`, `internal_error`, `needs_user_review`, `tool_unavailable`" }, { "type": "null" } ] }, "created_by": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["user", "bot"], "description": "One of: `user`, `bot`" } }, "additionalProperties": false, "required": ["id", "type"] }, { "type": "null" } ] }, "total_credits_used": { "type": "number", "description": "Premium AI credits consumed by this agent within the window." }, "credit_limit": { "oneOf": [ { "type": "number" }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "Enforced per-agent credit limit; null when none is configured, and \"hidden\" when the caller lacks full access to the agent." }, "runs_completed": { "type": "number", "description": "Number of runs recorded for this agent within the window." } }, "additionalProperties": false, "required": [ "object", "id", "name", "agent_type", "status", "pause_reason", "created_by", "total_credits_used", "credit_limit", "runs_completed" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/ai/plugins/{id}": { "get": { "summary": "Get a plugin directory", "operationId": "get-plugin-directory", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "examples": ["9b4a1d3f-1f0a-4c2a-9f0b-6c1f5a3d2e10"] } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "version_id": { "type": "string", "minLength": 64, "maxLength": 64, "description": "Opaque version identifier for the plugin directory. Compare this value for equality to determine whether the directory has changed. This matches the version_id in the corresponding plugin summary." }, "url": { "type": "string", "description": "Temporary signed URL for downloading the plugin directory as a gzipped tar archive." } }, "additionalProperties": false, "required": ["id", "version_id", "url"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "x-notion-docs-ref": "https://developers.notion.com/reference/unreleased/get-plugin-directory" } }, "/v1/rollout/{rollout_id}": { "get": { "summary": "Get a rollout", "operationId": "get-rollout", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "rollout_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Identifier returned by `POST /v1/rollout`. Rollouts are readable for up to 7 days." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "rolloutId": { "type": "string", "description": "Identifier for this rollout. Use it with GET /v1/rollout/:rollout_id when the result is not terminal." }, "status": { "type": "string", "enum": ["waiting", "running", "complete", "failed"], "description": "Current status of the rollout. Rollouts progress through waiting, running, and then complete or failed." }, "result": { "type": "object", "properties": { "output": { "description": "Inference output." }, "input": { "description": "Original rollout input. Omitted unless explicitly requested via `response.input`." }, "scores": { "description": "Grader results as name-to-score mappings." }, "metadata": { "description": "Inference metadata. Includes post-processor results, grader debug info, raw inference capture under `metadata.logging.rawInferences`, and `metadata.traceUrl` after a successful opt-in Braintrust logging flush." } }, "additionalProperties": false, "required": ["output"], "description": "Rollout result loaded from AI logging S3. Present when status is `complete`." }, "error": { "type": "string", "description": "Bounded failure message. Present when status is `failed`, including when the AI logging S3 output payload is no longer readable." } }, "additionalProperties": false, "required": ["rolloutId", "status"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/teamspaces/{team_id}": { "get": { "summary": "Get teamspace", "operationId": "get-teamspace", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the teamspace to retrieve." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "teamspace", "description": "The team object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the teamspace." }, "name": { "type": "string", "description": "The name of the teamspace." }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The description of the teamspace." }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "null" } ], "description": "The icon of the teamspace." }, "in_trash": { "type": "boolean", "description": "Whether the teamspace is in the trash." }, "visibility": { "type": "string", "enum": ["default", "open", "closed", "private"], "description": "The teamspace's visibility in the workspace." }, "settings": { "oneOf": [ { "type": "object", "properties": { "allow_members_to_invite_members": { "type": "boolean", "description": "Whether members can invite other members." }, "allow_members_to_change_sidebar": { "type": "boolean", "description": "Whether members can change the sidebar." }, "disable_invite_link": { "type": "boolean", "description": "Whether invite links are allowed." }, "disable_public_pages": { "type": "boolean", "description": "Whether public pages are allowed." }, "disable_guests": { "type": "boolean", "description": "Whether guests are allowed." }, "disable_restricted_members": { "type": "boolean", "description": "Whether restricted members are allowed." }, "disable_export": { "type": "boolean", "description": "Whether export is allowed." } }, "additionalProperties": false, "required": [ "allow_members_to_invite_members", "allow_members_to_change_sidebar", "disable_invite_link", "disable_public_pages", "disable_guests", "disable_restricted_members", "disable_export" ] }, { "type": "null" } ], "description": "The teamspace's settings." } }, "additionalProperties": false, "required": [ "object", "id", "name", "description", "icon", "in_trash", "visibility", "settings" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "patch": { "summary": "Update teamspace", "operationId": "update-teamspace", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the teamspace to update." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "examples": ["Engineering Team"], "description": "The name of the teamspace." }, "visibility": { "type": "string", "enum": ["default", "open", "closed", "private"], "description": "The teamspace's visibility in the workspace. Options include: default, open, closed, private." }, "description": { "type": "string", "examples": ["Team for engineering projects"], "description": "The description for the teamspace." }, "icon": { "$ref": "#/components/schemas/pageIconRequest", "description": "The icon for the teamspace." }, "settings": { "type": "object", "properties": { "allow_members_to_invite_members": { "type": "boolean", "description": "When true, members can invite other members. When false, only teamspace owners can. Corresponds to the 'Who can invite or remove teamspace members` setting." }, "allow_members_to_change_sidebar": { "type": "boolean", "description": "When true, members can edit the sidebar. When false, only teamspace owners can. Corresponds to the `Who can edit teamspace sidebar` setting." }, "disable_invite_link": { "type": "boolean", "description": "When true, invite links are disabled. Corresponds to the `Invite Link` toggle." }, "disable_public_pages": { "type": "boolean", "description": "When true, public pages are disabled. Corresponds to the `Disable publishing sites, forms, and public links` toggle." }, "disable_guests": { "type": "boolean", "description": "When true, guests are disabled and removed from the teamspace. Corresponds to the `Disable guests` toggle." }, "disable_restricted_members": { "type": "boolean", "description": "When true, restricted members are disabled and removed from the teamspace. Corresponds to the `Disable restricted members` toggle." }, "disable_export": { "type": "boolean", "description": "When true, exporting pages is disabled. Corresponds to the `Disable export` toggle." } }, "description": "The settings of the teamspace." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "teamspace", "description": "The team object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the teamspace." }, "name": { "type": "string", "description": "The name of the teamspace." }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The description of the teamspace." }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "null" } ], "description": "The icon of the teamspace." }, "in_trash": { "type": "boolean", "description": "Whether the teamspace is in the trash." }, "visibility": { "type": "string", "enum": ["default", "open", "closed", "private"], "description": "The teamspace's visibility in the workspace." }, "settings": { "oneOf": [ { "type": "object", "properties": { "allow_members_to_invite_members": { "type": "boolean", "description": "Whether members can invite other members." }, "allow_members_to_change_sidebar": { "type": "boolean", "description": "Whether members can change the sidebar." }, "disable_invite_link": { "type": "boolean", "description": "Whether invite links are allowed." }, "disable_public_pages": { "type": "boolean", "description": "Whether public pages are allowed." }, "disable_guests": { "type": "boolean", "description": "Whether guests are allowed." }, "disable_restricted_members": { "type": "boolean", "description": "Whether restricted members are allowed." }, "disable_export": { "type": "boolean", "description": "Whether export is allowed." } }, "additionalProperties": false, "required": [ "allow_members_to_invite_members", "allow_members_to_change_sidebar", "disable_invite_link", "disable_public_pages", "disable_guests", "disable_restricted_members", "disable_export" ] }, { "type": "null" } ], "description": "The teamspace's settings." } }, "additionalProperties": false, "required": [ "object", "id", "name", "description", "icon", "in_trash", "visibility", "settings" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/export": { "post": { "summary": "Export a page", "operationId": "initiate-page-export", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "blockId": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the page or block to export." } }, "required": ["blockId"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "export", "description": "The type of object, always 'export'." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the exported page or block." }, "pdf_export_url": { "type": "string", "description": "URL to download the page export (PDF)." }, "metadata_export_url": { "type": "string", "description": "URL to download the metadata export (JSON)." }, "comments_export_url": { "type": "string", "description": "URL to download the comments export (JSON)." }, "attachments_export_url": { "type": "string", "description": "URL to download the attachments export (JSON)." }, "permissions_export_url": { "type": "string", "description": "URL to download the permissions export (JSON)." } }, "additionalProperties": false, "required": [ "object", "id", "pdf_export_url", "metadata_export_url", "comments_export_url", "attachments_export_url", "permissions_export_url" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/agents": { "get": { "summary": "List agents", "operationId": "list-agents", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "name", "in": "query", "schema": { "type": "string", "description": "Filter agents by name (case-insensitive substring match)." } }, { "name": "agent_type", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent", "external" ], "description": "One of: `notion_ai`, `custom_agent`, `autofill_custom_agent`, `external`" }, "maxItems": 100, "minItems": 1, "description": "Filter agents by one or more agent types." } }, { "name": "agent_ids", "in": "query", "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": [ "notion_ai", "33333333-3333-3333-3333-333333333333" ], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ] }, "maxItems": 100, "minItems": 1, "description": "Filter agents by one or more agent IDs. Use `notion_ai` for Notion Agent (personal agent)." } }, { "name": "created_by", "in": "query", "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "me", "description": "Always `me`" } ] }, "maxItems": 100, "minItems": 1, "description": "Filter agents by one or more creator IDs. Use \"me\" for the user associated with the API token." } }, { "name": "start_cursor", "in": "query", "schema": { "type": "string", "description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results." } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of items from the full list desired in the response. Maximum: 100" } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "agent", "description": "Always `agent`" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "agent", "description": "Always `agent`" }, "id": { "$ref": "#/components/schemas/idResponse" }, "agent_type": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent", "external" ], "description": "Agent kind: the Notion AI personal agent, a custom agent, a database autofill custom agent, or an external agent." }, "name": { "type": "string" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "instructions_page_id": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_agent_avatar", "description": "Type of icon. In this case, a custom agent avatar." }, "custom_agent_avatar": { "type": "object", "properties": { "static_url": { "type": "string", "description": "The URL of the static custom agent avatar." }, "animated_url": { "type": "string", "description": "The URL of the animated custom agent avatar." } }, "additionalProperties": false, "required": ["static_url", "animated_url"], "description": "The static and animated URLs for the agent avatar." } }, "additionalProperties": false, "required": ["type", "custom_agent_avatar"] }, { "type": "null" } ] }, "version": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the published artifact." }, "number": { "type": "number", "description": "The version number." }, "published_at": { "type": "string", "description": "The ISO 8601 timestamp when this version was published." } }, "additionalProperties": false, "required": ["id", "number", "published_at"] }, { "type": "null" } ] }, "model": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "auto", "description": "Always `auto`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "pinned", "description": "Always `pinned`" }, "id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The public model this agent maps to (e.g. \"claude-sonnet-5\"), or null for a pre-release / early-access model." } }, "additionalProperties": false, "required": ["type", "id"] } ], "description": "The model the agent runs on: auto (Notion selects) or a pinned model." }, "connections": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "notion", "description": "Always `notion`" }, "name": { "type": "string" }, "account": { "type": "null" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "database_property", "description": "Always `database_property`" }, "data_source_id": { "type": "string" }, "property_id": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "data_source_id", "property_id" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "agent", "description": "Always `agent`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "workspace", "description": "Always `workspace`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "owner_private_pages", "description": "Always `owner_private_pages`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "web_search", "description": "Always `web_search`" }, "allowed_domains": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Domains web search is restricted to, or null when unrestricted." } }, "additionalProperties": false, "required": [ "type", "allowed_domains" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "notion_help_docs_search", "description": "Always `notion_help_docs_search`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Content roles (\"reader\" | \"comment_only\" | \"read_and_write\" | \"editor\") for scoped targets, or search verbs (\"allow\" | \"disallow\") for the search targets." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack", "description": "Always `slack`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "slack_workspace", "description": "Always `slack_workspace`" }, "team_id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "team_id"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The linked Slack workspace, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "slack_channel", "description": "Always `slack_channel`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack_all_public_channels", "description": "Always `slack_all_public_channels`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack_all_channels", "description": "Always `slack_all_channels`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Slack verbs granted on this target (\"read\" | \"write\" | \"reply_in_thread\" | \"react\")." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "discord", "description": "Always `discord`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "discord_server", "description": "Always `discord_server`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The linked Discord server, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "discord_channel", "description": "Always `discord_channel`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "discord_all_channels", "description": "Always `discord_all_channels`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Discord verbs granted on this target (\"read\" | \"write\" | \"reply_in_thread\" | \"react\")." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_host": { "type": "string", "description": "The MCP server host (never the full URL, which can carry credentials or private path components)." } }, "additionalProperties": false, "required": ["type", "server_host"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The MCP server host, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "enabled_tools": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["name", "title"] }, "maxItems": 100 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The tools the agent may call, null when all tools are enabled (including any the server adds later), or \"hidden\" when the caller lacks edit access to the agent." }, "run_tools_automatically": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Whether read tool calls run without a confirmation step." }, "write": { "type": "boolean", "description": "Whether write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": ["read", "write"], "description": "Whether read / write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": [ "type", "name", "account", "enabled_tools", "run_tools_automatically" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_mcp_server", "description": "Always `custom_mcp_server`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_host": { "type": "string", "description": "The MCP server host (never the full URL, which can carry credentials or private path components)." } }, "additionalProperties": false, "required": ["type", "server_host"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The MCP server host, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "enabled_tools": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["name", "title"] }, "maxItems": 100 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The tools the agent may call, null when all tools are enabled (including any the server adds later), or \"hidden\" when the caller lacks edit access to the agent." }, "run_tools_automatically": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Whether read tool calls run without a confirmation step." }, "write": { "type": "boolean", "description": "Whether write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": ["read", "write"], "description": "Whether read / write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": [ "type", "name", "account", "enabled_tools", "run_tools_automatically" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana", "box", "browser", "calendar", "computer", "confluence", "cursor", "files", "fs", "github", "gmail", "google_calendar", "google_drive", "google_drive_oauth", "gtm", "helpdocs", "images", "jira", "linear", "mail", "marketplace", "memory", "microsoft_teams", "outlook", "salesforce", "search", "security", "sharepoint", "skills", "system", "test", "web", "webhooks", "worker", "workers" ], "description": "The connector's machine name (e.g. \"github\", \"google_drive\")." }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider-side account identifier, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "The scopes granted on this target." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] } ] }, "maxItems": 100, "description": "Non-Notion integrations the agent is connected to, using the same account and permission shape as get agent." }, "status": { "type": "string", "enum": ["active", "disabled", "deleted"], "description": "Agent status. Disabled agents remain listed; deleted agents are currently excluded from list responses." }, "created_by": { "oneOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "user", "description": "Always `user`" }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the user that created this agent." } }, "additionalProperties": false, "required": ["object", "id"] }, { "type": "null" } ] }, "created_time": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Date and time when this agent was created, or null for the personal agent." }, "last_edited_time": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Date and time when this agent was last edited, or null for the personal agent." }, "last_run_time": { "oneOf": [ { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T" }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "Date and time when this agent was last invoked, null when no invocation is available, or \"hidden\" when the caller lacks edit access to the agent." } }, "additionalProperties": false, "required": [ "object", "id", "agent_type", "name", "description", "instructions_page_id", "icon", "version", "model", "connections", "status", "created_by", "created_time", "last_edited_time", "last_run_time" ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "title": "Cursor", "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "deprecated": true, "x-notion-docs-ref": "https://developers.notion.com/reference/internal/list-agents" } }, "/v1/connections": { "get": { "summary": "List connections", "operationId": "list-connections", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "include_types", "in": "query", "schema": { "type": "boolean", "description": "Whether to include actor-specific TypeScript declarations for notion-script." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "connection_list", "description": "Always connection_list." }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable ID of the configured connection." }, "key": { "type": "string", "description": "Generated convenience key accepted by connection selectors. Use the stable ID when a key matches multiple connections." }, "name": { "type": "string", "description": "User-visible connection name." }, "type": { "type": "string", "description": "Connection provider type, such as slack." }, "is_default": { "type": "boolean", "description": "Whether this is the unambiguous default for its provider type." }, "actions": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Credential- and feature-gate-filtered actions available through this connection." } }, "additionalProperties": false, "required": [ "id", "key", "name", "type", "is_default", "actions" ] }, "maxItems": 100, "description": "Connections visible to the authenticated principal." }, "type_bundle": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Sandbox-relative TypeScript declaration path." }, "content": { "type": "string", "description": "TypeScript declaration content." } }, "additionalProperties": false, "required": ["path", "content"] }, "maxItems": 200, "description": "TypeScript files for the current actor's connections." }, "version": { "type": "string", "description": "Content hash for the delivered type bundle." } }, "additionalProperties": false, "required": ["files", "version"], "description": "Actor-specific TypeScript declarations requested by the sandbox runtime." } }, "additionalProperties": false, "required": ["object", "connections"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/data_sources": { "get": { "summary": "List data sources", "operationId": "get-databases", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "start_cursor", "in": "query", "schema": { "type": "string", "description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results." } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of items from the full list desired in the response. Maximum: 100" } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "next_cursor": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "has_more": { "type": "boolean" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/partialDataSourceObjectResponse" }, { "$ref": "#/components/schemas/dataSourceObjectResponse" } ] } }, "type": { "type": "string", "const": "data_source", "description": "Always `data_source`" }, "data_source": { "$ref": "#/components/schemas/emptyObject" }, "request_status": { "$ref": "#/components/schemas/requestStatusResponse" } }, "required": [ "object", "next_cursor", "has_more", "results", "type", "data_source" ], "additionalProperties": false } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/external_agent_stub/{agent_id}/sessions/{session_id}/events": { "get": { "summary": "List external agent stub session events", "operationId": "list-external-agent-stub-session-events", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "33333333-3333-3333-3333-333333333333", "description": "Always `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent backing this external agent session." } }, { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The provider-owned session ID returned when the session was created." } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Opaque cursor returned by a previous call. Only events strictly after this cursor are returned." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "assistant.thinking", "description": "Always `assistant.thinking`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "assistant.message", "description": "Always `assistant.message`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "tool.started", "description": "Always `tool.started`" }, "tool_call_id": { "type": "string" }, "tool_name": { "type": "string" }, "input": {} }, "additionalProperties": false, "required": ["type", "tool_call_id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "tool.output", "description": "Always `tool.output`" }, "tool_call_id": { "type": "string" }, "output": {}, "is_error": { "type": "boolean" } }, "additionalProperties": false, "required": ["type", "tool_call_id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "error", "description": "Always `error`" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "additional_data": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 } ] } } }, "additionalProperties": false, "required": ["code", "message", "retryable"] } }, "additionalProperties": false, "required": ["type", "error"] } ] }, "maxItems": 100 }, "is_running": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "additionalProperties": false, "required": ["events", "is_running"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/ai/plugins": { "get": { "summary": "List skills plugins", "operationId": "list-skills-plugins", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of items to return. Maximum: 100." } }, { "name": "start_cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9]+$", "description": "An opaque cursor returned by the previous page of results." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "version_id": { "type": "string", "minLength": 64, "maxLength": 64, "description": "Opaque version identifier for the plugin. Compare this value for equality to determine whether the plugin has changed." } }, "additionalProperties": false, "required": ["id", "name", "description", "version_id"] }, "maxItems": 100 }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "has_more": { "type": "boolean" }, "type": { "type": "string", "const": "plugin", "description": "Always `plugin`" } }, "additionalProperties": false, "required": [ "object", "results", "next_cursor", "has_more", "type" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "x-notion-docs-ref": "https://developers.notion.com/reference/unreleased/list-skills-plugins" } }, "/v1/teamspaces/{team_id}/membership": { "get": { "summary": "Lists team membership (users/groups that are owners/members) of a team.", "operationId": "listTeamMembership", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the teamspace to retrieve membership for." } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of Team Membership desired in the response. Maximum: 100" } }, { "name": "start_cursor", "in": "query", "schema": { "type": "string", "description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Indicates this is a list response." }, "type": { "type": "string", "const": "teamspace_member", "description": "The object type contained in the results array." }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "teamspace_member", "description": "The teamspace member object type name." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the user or group on the teamspace." }, "type": { "type": "string", "enum": ["person", "group"], "description": "Type of the member: person or group." }, "membership": { "type": "string", "enum": ["owner", "member"], "description": "Role of the member within the teamspace." } }, "additionalProperties": false, "required": ["object", "id", "type", "membership"] }, "maxItems": 100, "description": "Array of teamspace membership entries." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the teamspace whose membership is listed." }, "next_cursor": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ], "description": "Cursor for the next page of results, or null if there are no more results." }, "has_more": { "type": "boolean", "description": "Whether there are more results after this page." } }, "additionalProperties": false, "required": [ "object", "type", "results", "id", "next_cursor", "has_more" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "patch": { "summary": "Updates team membership for a given team.", "operationId": "update-team-membership", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the teamspace to update membership for." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "entity_id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the entity (person or group)." }, "entity_type": { "type": "string", "enum": ["person", "group"], "description": "The type of entity being added/updated/removed." } }, "required": ["entity_id", "entity_type"] }, { "oneOf": [ { "type": "object", "properties": { "op": { "type": "string", "const": "add", "description": "Always `add`" }, "membership": { "type": "string", "enum": ["owner", "member"], "description": "Whether to add the entity as a teamspace owner or member." } }, "required": ["op", "membership"], "title": "Add" }, { "type": "object", "properties": { "op": { "type": "string", "const": "replace", "description": "Always `replace`" }, "membership": { "type": "string", "enum": ["owner", "member"], "description": "Whether the entity should be an owner or member." } }, "required": ["op", "membership"], "title": "Replace" }, { "type": "object", "properties": { "op": { "type": "string", "const": "remove", "description": "Always `remove`" } }, "required": ["op"], "title": "Remove" } ] } ] }, "maxItems": 100, "description": "Array of operations to perform on team's membership." } }, "required": ["operations"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/emptyObject" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/teamspaces/{team_id}/permissions": { "get": { "summary": "List permission roles for various entities in a teamspace.", "operationId": "listTeamPermissions", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the teamspace to retrieve permissions for" } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of Team Permissions desired in the response. Maximum: 100" } }, { "name": "start_cursor", "in": "query", "schema": { "type": "string", "description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Indicates this is a list response." }, "type": { "type": "string", "const": "teamspace_permission", "description": "The object type contained in the results array." }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "teamspace_permission", "description": "Indicates this is a teamspace permission response." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of corresponding permission type. E.g. space, team (for members and owners), group, or person id." }, "type": { "type": "string", "enum": [ "space", "owners", "members", "group", "person" ], "description": "Type of permission: space, team owners, team members, custom group role, or custom person role." }, "role": { "type": "string", "enum": [ "can_read", "can_comment", "can_edit", "full_access" ], "description": "Permission role within the teamspace." } }, "additionalProperties": false, "required": ["object", "id", "type", "role"] }, "maxItems": 100, "description": "Array of teamspace permission entries." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the teamspace whose permissions are listed." }, "next_cursor": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ], "description": "Cursor for the next page of results, or null if there are no more results." }, "has_more": { "type": "boolean", "description": "Whether there are more results after this page." } }, "additionalProperties": false, "required": [ "object", "type", "results", "id", "next_cursor", "has_more" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "patch": { "summary": "Updates permission levels for a given teamspace.", "operationId": "update-teamspace-permissions", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the teamspace to update permissions for." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the entity (space, team, group, or person)." }, "type": { "type": "string", "enum": [ "space", "owners", "members", "group", "person" ], "description": "The type of entity being assigned permissions." }, "role": { "type": "string", "enum": [ "none", "can_read", "can_comment", "can_edit", "full_access" ], "description": "The permission role for the entity in the teamspace." } }, "required": ["id", "type", "role"] }, "maxItems": 100, "description": "Array of operations to perform on team's permissions." } }, "required": ["operations"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/emptyObject" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/threads/{thread_id}/messages": { "get": { "summary": "List thread messages", "operationId": "list-thread-messages", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the thread." } }, { "name": "verbose", "in": "query", "schema": { "type": "boolean", "description": "Whether to include verbose agent output (thinking, raw tool names, tool calls, and tool results). Defaults to true." } }, { "name": "role", "in": "query", "schema": { "type": "string", "enum": ["user", "agent"], "description": "Filter messages by role (user or agent)." } }, { "name": "start_cursor", "in": "query", "schema": { "type": "string", "description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results." } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of items from the full list desired in the response. Maximum: 100" } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "thread_message", "description": "Always `thread_message`" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "thread_message", "description": "Always `thread_message`" }, "id": { "$ref": "#/components/schemas/idResponse" }, "role": { "type": "string", "enum": ["user", "agent"], "description": "One of: `user`, `agent`" }, "content": { "type": "string" }, "created_time": { "type": "string", "format": "date-time", "description": "Date and time when this message was created." }, "parent": { "type": "object", "properties": { "type": { "type": "string", "const": "thread", "description": "The parent type." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the parent thread." } }, "additionalProperties": false, "required": ["type", "id"] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "content_type": { "type": "string" }, "url": { "type": "string" }, "expiry_time": { "type": "string", "format": "date-time", "description": "The time when the attachment URL will expire." } }, "additionalProperties": false, "required": ["name", "content_type", "url"] }, "maxItems": 100 }, "content_parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Always `text`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "thinking", "description": "Always `thinking`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "tool_call", "description": "Always `tool_call`" }, "tool_call_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_name": { "type": "string" }, "input": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "agent_step_id": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "tool_call_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_name": { "type": "string" }, "tool_type": { "type": "string" }, "state": { "type": "string" }, "input": { "oneOf": [ {}, { "type": "null" } ] }, "output": { "oneOf": [ {}, { "type": "null" } ] }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "started_at": { "type": "integer", "minimum": 0 }, "finished_at": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "duration_ms": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "id", "agent_step_id", "tool_call_id", "tool_name", "tool_type", "state", "input", "output", "error", "started_at", "finished_at", "duration_ms" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "tool_call_id", "tool_name", "input" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "follow_ups", "description": "Always `follow_ups`" }, "follow_ups": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false, "required": ["label", "message"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "follow_ups"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_agent_template_picker", "description": "Always `custom_agent_template_picker`" } }, "additionalProperties": false, "required": ["type"] } ] }, "maxItems": 100 }, "pending_user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "type": { "type": "string", "const": "tool_confirmation", "description": "Always `tool_confirmation`" }, "title": { "type": "string" }, "requirements": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "general", "description": "Always `general`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "manage_workers", "description": "Always `manage_workers`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "url_safety", "description": "Always `url_safety`" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "required_by_workspace_policy": { "type": "boolean" } }, "additionalProperties": false, "required": ["type", "urls"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "permission_escalation", "description": "Always `permission_escalation`" }, "destination_title": { "type": "string" }, "source_titles": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "delete_content", "description": "Always `delete_content`" }, "page_count": { "type": "integer", "minimum": 0 }, "database_count": { "type": "integer", "minimum": 0 }, "meeting_notes_block_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "type", "page_count", "database_count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "connect_integration", "description": "Always `connect_integration`" }, "integration_type": { "type": "string" }, "integration_name": { "type": "string" }, "handoff_url": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "integration_type", "integration_name", "handoff_url" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_mode", "description": "Always `admin_mode`" }, "explanation": { "type": "string" } }, "additionalProperties": false, "required": ["type"] } ], "title": "Pending user action requirement" }, "maxItems": 100 }, "options": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "const": "approve", "description": "Always `approve`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "reject", "description": "Always `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "use_connection", "description": "Always `use_connection`" }, "label": { "type": "string" }, "input": { "type": "object", "properties": { "type": { "type": "string", "const": "connection_id", "description": "Always `connection_id`" }, "required": { "type": "boolean", "const": true, "description": "Always `true`" } }, "additionalProperties": false, "required": ["type", "required"] } }, "additionalProperties": false, "required": ["id", "label", "input"] } ], "title": "Pending user action option" }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "id", "type", "title", "requirements", "options" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "object", "id", "role", "content", "created_time", "parent" ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "title": "Cursor", "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "deprecated": true, "x-notion-docs-ref": "https://developers.notion.com/reference/internal/list-thread-messages" }, "post": { "summary": "Send a thread message", "operationId": "send-thread-message", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the thread." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 10000, "description": "The message to send to the agent." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_upload": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of a FileUpload object that has the status `uploaded`." } }, "required": ["id"], "description": "ID of a FileUpload object that has the status `uploaded`." }, "type": { "type": "string", "const": "file_upload", "description": "The type of the attachment. Only supports \"file_upload\"." }, "name": { "type": "string", "description": "An optional display name override for the attachment." } }, "required": ["file_upload"] }, "maxItems": 100, "description": "An array of file uploads to attach to this chat turn. Use the File Upload APIs to create uploads and pass their IDs here." }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "maxLength": 200, "description": "An external user identifier supplied by the API caller for lifecycle metadata and correlation. This does not change the Notion actor used for authorization." } }, "additionalProperties": false, "description": "Optional caller-provided metadata associated with the chat invocation." }, "prompt_context": { "type": "string", "maxLength": 10000, "description": "Additional caller-provided context for the agent to consider while responding." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat.invocation", "description": "Always `chat.invocation`" }, "agent_id": { "type": "string" }, "thread_id": { "type": "string" }, "invocation_id": { "type": "string" }, "status": { "type": "string", "const": "pending", "description": "Always `pending`" } }, "additionalProperties": false, "required": [ "object", "agent_id", "thread_id", "invocation_id", "status" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "deprecated": true } }, "/v1/agents/{agent_id}/threads": { "get": { "summary": "List threads", "operationId": "list-threads", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent. Use a UUID for custom agents or `notion_ai` for Notion Agent (personal agent); the reserved UUID `33333333-3333-3333-3333-333333333333` remains supported for backward compatibility." } }, { "name": "id", "in": "query", "schema": { "$ref": "#/components/schemas/idRequest", "description": "Filter threads by ID (exact match)." } }, { "name": "title", "in": "query", "schema": { "type": "string", "description": "Filter threads by title (case-insensitive substring match)." } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "requires_action", "completed", "failed"], "description": "Filter threads by status." } }, { "name": "activity", "in": "query", "schema": { "type": "string", "enum": ["all", "pending", "in_progress", "failed", "success"], "description": "Filter threads by agent activity state. Defaults to `all`." } }, { "name": "created_by", "in": "query", "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "me", "description": "Always `me`" } ] }, "maxItems": 100, "minItems": 1, "description": "Filter threads by one or more creator IDs. Use \"me\" for the API bot and user associated with the API token." } }, { "name": "last_used_by", "in": "query", "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "me", "description": "Always `me`" } ] }, "maxItems": 100, "minItems": 1, "description": "Filter threads by one or more IDs of actors who last used them. Use \"me\" for the API bot and user associated with the API token." } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["created_time", "last_used_time"], "description": "Timestamp used to sort threads. Defaults to `created_time`." } }, { "name": "sort_direction", "in": "query", "schema": { "type": "string", "enum": ["ascending", "descending"], "description": "Sort direction. Defaults to `descending`." } }, { "name": "start_cursor", "in": "query", "schema": { "type": "string", "description": "If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results." } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of items from the full list desired in the response. Maximum: 100" } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "thread", "description": "Always `thread`" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "thread", "description": "Always `thread`" }, "id": { "$ref": "#/components/schemas/idResponse" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "requires_action", "completed", "failed" ], "description": "One of: `pending`, `requires_action`, `completed`, `failed`" }, "created_time": { "type": "string", "format": "date-time", "description": "Date and time when this thread was created." }, "last_edited_time": { "type": "string", "format": "date-time", "description": "Date and time when this thread was last updated." }, "created_by": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the actor that created this thread: a bot for an integration-created thread, a user for one created in the Notion app." }, "type": { "type": "string", "enum": ["bot", "user"], "description": "The creator type. Threads a caller can see because it has access to the agent, such as a trigger's runs or a teammate's chats, may be created by either a bot or a user." } }, "additionalProperties": false, "required": ["id", "type"] }, "agent_version": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the published artifact." }, "number": { "type": "number", "description": "The version number." }, "published_at": { "type": "string", "description": "The ISO 8601 timestamp when this version was published." } }, "additionalProperties": false, "required": ["id", "number", "published_at"] }, { "type": "null" } ] }, "models": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "auto", "description": "Always `auto`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "pinned", "description": "Always `pinned`" }, "ids": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "maxItems": 100, "description": "The public model this thread is pinned to (e.g. \"claude-sonnet-5\"), with null for a pre-release / early-access model. Empty when the thread has no model recorded yet. Reflects the thread's configuration at creation, so a model changed mid-conversation is not reflected here." } }, "additionalProperties": false, "required": ["type", "ids"] } ] }, "error": { "type": "string" }, "trigger_type": { "type": "string", "description": "How this thread started: the type of the trigger that ran it, or \"chat\"." }, "type_labels": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Labels describing how the thread ran (triggered, chat, setup). Null when the caller lacks edit access to the agent." }, "chat_user_emails": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Emails of the users who participated in this thread. Null when the caller lacks edit access to the agent." }, "tool_types": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Types of tool this thread called. Null when the caller lacks edit access to the agent." }, "tool_call_count": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Number of tool calls in this thread. Null when the caller lacks edit access to the agent." }, "credits_used": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium AI credits this thread consumed. Null when the caller lacks edit access to the agent." }, "runs_completed": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Runs completed in this thread. Null when the caller lacks edit access to the agent, or when the thread predates run tracking." }, "pending_user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "type": { "type": "string", "const": "tool_confirmation", "description": "Always `tool_confirmation`" }, "title": { "type": "string" }, "requirements": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "general", "description": "Always `general`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "manage_workers", "description": "Always `manage_workers`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "url_safety", "description": "Always `url_safety`" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "required_by_workspace_policy": { "type": "boolean" } }, "additionalProperties": false, "required": ["type", "urls"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "permission_escalation", "description": "Always `permission_escalation`" }, "destination_title": { "type": "string" }, "source_titles": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "delete_content", "description": "Always `delete_content`" }, "page_count": { "type": "integer", "minimum": 0 }, "database_count": { "type": "integer", "minimum": 0 }, "meeting_notes_block_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "type", "page_count", "database_count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "connect_integration", "description": "Always `connect_integration`" }, "integration_type": { "type": "string" }, "integration_name": { "type": "string" }, "handoff_url": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "integration_type", "integration_name", "handoff_url" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_mode", "description": "Always `admin_mode`" }, "explanation": { "type": "string" } }, "additionalProperties": false, "required": ["type"] } ], "title": "Pending user action requirement" }, "maxItems": 100 }, "options": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "const": "approve", "description": "Always `approve`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "reject", "description": "Always `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "use_connection", "description": "Always `use_connection`" }, "label": { "type": "string" }, "input": { "type": "object", "properties": { "type": { "type": "string", "const": "connection_id", "description": "Always `connection_id`" }, "required": { "type": "boolean", "const": true, "description": "Always `true`" } }, "additionalProperties": false, "required": ["type", "required"] } }, "additionalProperties": false, "required": ["id", "label", "input"] } ], "title": "Pending user action option" }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "id", "type", "title", "requirements", "options" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "object", "id", "title", "status", "created_time", "last_edited_time", "created_by", "agent_version", "models" ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "title": "Cursor", "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "deprecated": true, "x-notion-docs-ref": "https://developers.notion.com/reference/internal/list-threads" } }, "/v1/tools/agents/{agent_id}/token": { "post": { "summary": "Mint a workflow harness bot token for an allowlisted custom agent", "operationId": "mint-agent-harness-token", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the custom agent to mint a harness bot token for. Must be allowlisted server-side." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The minted workflow harness bot token. Treat as a secret; it is revoked at the expiry time." }, "expires_at": { "type": "integer", "description": "Unix epoch milliseconds when the token expires. Mint a new token before this time." }, "space_id": { "type": "string", "description": "The workspace ID the token is scoped to." } }, "additionalProperties": false, "required": ["token", "expires_at", "space_id"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/oauth/ema/resolve": { "post": { "summary": "Resolve an EMA ID-JAG identity to an MCP access token", "operationId": "ema-resolve-identity", "security": [ { "basicAuth": [] } ], "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "subject": { "type": "string" }, "oauth_client_id": { "type": "string" }, "resource": { "type": "string" }, "requested_scope": { "type": "array", "items": { "type": "string" } }, "email": { "type": "string" }, "redirect_uri": { "type": "string" } }, "required": [ "issuer", "subject", "oauth_client_id", "resource", "requested_scope" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "space_id": { "type": "string", "format": "uuid" }, "access_token": { "type": "string" }, "has_advanced_tools": { "type": "boolean" }, "has_ai_access": { "type": "boolean" }, "request_id": { "type": "string", "format": "uuid" } }, "required": ["user_id", "space_id", "access_token"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_403" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_500" } } } } } } }, "/v1/oauth/ema/trusted-issuer": { "post": { "summary": "Resolve an EMA trusted issuer", "operationId": "ema-resolve-trusted-issuer", "security": [ { "basicAuth": [] } ], "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" } }, "required": ["issuer"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "required": ["issuer"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_403" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_oauth_500" } } } } } } }, "/v1/agents/query": { "post": { "summary": "Query agents", "operationId": "query-agents", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search agent names and descriptions using a case-insensitive substring match." }, "filter": { "oneOf": [ { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "const": "id" }, "id": { "type": "object", "properties": { "equals": { "type": "string" } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "id"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "agent_type" }, "select": { "type": "object", "properties": { "equals": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent" ] } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "select"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_by" }, "people": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": ["contains"], "additionalProperties": false } }, "required": ["property", "people"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_time" }, "date": { "type": "object", "properties": { "after": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "required": ["property", "date"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "favorited" }, "checkbox": { "type": "object", "properties": { "equals": { "type": "boolean" } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "checkbox"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "connections" }, "mcp_server": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": ["contains"], "additionalProperties": false } }, "required": ["property", "mcp_server"], "additionalProperties": false } ] }, { "oneOf": [ { "type": "object", "properties": { "and": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "const": "id" }, "id": { "type": "object", "properties": { "equals": { "type": "string" } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "id"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "agent_type" }, "select": { "type": "object", "properties": { "equals": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent" ] } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "select"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_by" }, "people": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": ["contains"], "additionalProperties": false } }, "required": ["property", "people"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_time" }, "date": { "type": "object", "properties": { "after": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "required": ["property", "date"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "favorited" }, "checkbox": { "type": "object", "properties": { "equals": { "type": "boolean" } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "checkbox"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "connections" }, "mcp_server": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": ["contains"], "additionalProperties": false } }, "required": [ "property", "mcp_server" ], "additionalProperties": false } ] }, { "oneOf": [ { "type": "object", "properties": { "and": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "const": "id" }, "id": { "type": "object", "properties": { "equals": { "type": "string" } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "agent_type" }, "select": { "type": "object", "properties": { "equals": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent" ] } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "select" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_by" }, "people": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": [ "contains" ], "additionalProperties": false } }, "required": [ "property", "people" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_time" }, "date": { "type": "object", "properties": { "after": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "required": [ "property", "date" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "favorited" }, "checkbox": { "type": "object", "properties": { "equals": { "type": "boolean" } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "checkbox" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "connections" }, "mcp_server": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": [ "contains" ], "additionalProperties": false } }, "required": [ "property", "mcp_server" ], "additionalProperties": false } ] } } }, "required": ["and"], "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "const": "id" }, "id": { "type": "object", "properties": { "equals": { "type": "string" } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "agent_type" }, "select": { "type": "object", "properties": { "equals": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent" ] } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "select" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_by" }, "people": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": [ "contains" ], "additionalProperties": false } }, "required": [ "property", "people" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_time" }, "date": { "type": "object", "properties": { "after": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "required": [ "property", "date" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "favorited" }, "checkbox": { "type": "object", "properties": { "equals": { "type": "boolean" } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "checkbox" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "connections" }, "mcp_server": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": [ "contains" ], "additionalProperties": false } }, "required": [ "property", "mcp_server" ], "additionalProperties": false } ] } } }, "required": ["or"], "additionalProperties": false } ] } ] } } }, "required": ["and"], "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "const": "id" }, "id": { "type": "object", "properties": { "equals": { "type": "string" } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "id"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "agent_type" }, "select": { "type": "object", "properties": { "equals": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent" ] } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "select"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_by" }, "people": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": ["contains"], "additionalProperties": false } }, "required": ["property", "people"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_time" }, "date": { "type": "object", "properties": { "after": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "required": ["property", "date"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "favorited" }, "checkbox": { "type": "object", "properties": { "equals": { "type": "boolean" } }, "required": ["equals"], "additionalProperties": false } }, "required": ["property", "checkbox"], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "connections" }, "mcp_server": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": ["contains"], "additionalProperties": false } }, "required": [ "property", "mcp_server" ], "additionalProperties": false } ] }, { "oneOf": [ { "type": "object", "properties": { "and": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "const": "id" }, "id": { "type": "object", "properties": { "equals": { "type": "string" } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "agent_type" }, "select": { "type": "object", "properties": { "equals": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent" ] } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "select" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_by" }, "people": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": [ "contains" ], "additionalProperties": false } }, "required": [ "property", "people" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_time" }, "date": { "type": "object", "properties": { "after": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "required": [ "property", "date" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "favorited" }, "checkbox": { "type": "object", "properties": { "equals": { "type": "boolean" } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "checkbox" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "connections" }, "mcp_server": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": [ "contains" ], "additionalProperties": false } }, "required": [ "property", "mcp_server" ], "additionalProperties": false } ] } } }, "required": ["and"], "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "const": "id" }, "id": { "type": "object", "properties": { "equals": { "type": "string" } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "agent_type" }, "select": { "type": "object", "properties": { "equals": { "type": "string", "enum": [ "notion_ai", "custom_agent", "autofill_custom_agent" ] } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "select" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_by" }, "people": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": [ "contains" ], "additionalProperties": false } }, "required": [ "property", "people" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "created_time" }, "date": { "type": "object", "properties": { "after": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "required": [ "property", "date" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "favorited" }, "checkbox": { "type": "object", "properties": { "equals": { "type": "boolean" } }, "required": ["equals"], "additionalProperties": false } }, "required": [ "property", "checkbox" ], "additionalProperties": false }, { "type": "object", "properties": { "property": { "type": "string", "const": "connections" }, "mcp_server": { "type": "object", "properties": { "contains": { "type": "string" } }, "required": [ "contains" ], "additionalProperties": false } }, "required": [ "property", "mcp_server" ], "additionalProperties": false } ] } } }, "required": ["or"], "additionalProperties": false } ] } ] } } }, "required": ["or"], "additionalProperties": false } ] } ], "description": "Filter agents by public properties, optionally combined with and/or." }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "enum": ["created_time", "last_used_time"], "description": "Timestamp used to sort agents." }, "direction": { "type": "string", "enum": ["ascending", "descending"], "description": "Sort direction." } }, "required": ["timestamp", "direction"] }, "maxItems": 2, "minItems": 1, "description": "Ordered sort precedence. Defaults to created_time descending." }, "start_cursor": { "type": "string", "description": "Opaque continuation cursor from the previous page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of agents to return. Maximum: 100." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "agent", "description": "Always `agent`" }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "agent", "description": "Always `agent`" }, "id": { "$ref": "#/components/schemas/idResponse" }, "agent_type": { "type": "string", "enum": [ "custom_agent", "autofill_custom_agent" ], "description": "What kind of agent this is: \"custom_agent\" is a standalone agent you chat with; \"autofill_custom_agent\" fills a database property." }, "name": { "type": "string" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "instructions_page_id": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_agent_avatar", "description": "Type of icon. In this case, a custom agent avatar." }, "custom_agent_avatar": { "type": "object", "properties": { "static_url": { "type": "string", "description": "The URL of the static custom agent avatar." }, "animated_url": { "type": "string", "description": "The URL of the animated custom agent avatar." } }, "additionalProperties": false, "required": [ "static_url", "animated_url" ], "description": "The static and animated URLs for the agent avatar." } }, "additionalProperties": false, "required": ["type", "custom_agent_avatar"] }, { "type": "null" } ] }, "model": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The pinned model ID, or null when no model is pinned." }, "model_mode": { "oneOf": [ { "type": "string", "enum": ["pinned", "auto"], "description": "One of: `pinned`, `auto`" }, { "type": "null" } ], "description": "Whether the model is pinned or selected automatically; null when unavailable." }, "connections": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "notion", "description": "Always `notion`" }, "name": { "type": "string" }, "account": { "type": "null" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "database_property", "description": "Always `database_property`" }, "data_source_id": { "type": "string" }, "property_id": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "data_source_id", "property_id" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "agent", "description": "Always `agent`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "workspace", "description": "Always `workspace`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "owner_private_pages", "description": "Always `owner_private_pages`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "web_search", "description": "Always `web_search`" }, "allowed_domains": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Domains web search is restricted to, or null when unrestricted." } }, "additionalProperties": false, "required": [ "type", "allowed_domains" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "notion_help_docs_search", "description": "Always `notion_help_docs_search`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Content roles (\"reader\" | \"comment_only\" | \"read_and_write\" | \"editor\") for scoped targets, or search verbs (\"allow\" | \"disallow\") for the search targets." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack", "description": "Always `slack`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "slack_workspace", "description": "Always `slack_workspace`" }, "team_id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "team_id"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The linked Slack workspace, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "slack_channel", "description": "Always `slack_channel`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack_all_public_channels", "description": "Always `slack_all_public_channels`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack_all_channels", "description": "Always `slack_all_channels`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Slack verbs granted on this target (\"read\" | \"write\" | \"reply_in_thread\" | \"react\")." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "discord", "description": "Always `discord`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "discord_server", "description": "Always `discord_server`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The linked Discord server, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "discord_channel", "description": "Always `discord_channel`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "discord_all_channels", "description": "Always `discord_all_channels`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Discord verbs granted on this target (\"read\" | \"write\" | \"reply_in_thread\" | \"react\")." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_host": { "type": "string", "description": "The MCP server host (never the full URL, which can carry credentials or private path components)." } }, "additionalProperties": false, "required": [ "type", "server_host" ] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The MCP server host, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "enabled_tools": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["name", "title"] }, "maxItems": 100 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The tools the agent may call, null when all tools are enabled (including any the server adds later), or \"hidden\" when the caller lacks edit access to the agent." }, "run_tools_automatically": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Whether read tool calls run without a confirmation step." }, "write": { "type": "boolean", "description": "Whether write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": ["read", "write"], "description": "Whether read / write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": [ "type", "name", "account", "enabled_tools", "run_tools_automatically" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_mcp_server", "description": "Always `custom_mcp_server`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_host": { "type": "string", "description": "The MCP server host (never the full URL, which can carry credentials or private path components)." } }, "additionalProperties": false, "required": [ "type", "server_host" ] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The MCP server host, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "enabled_tools": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["name", "title"] }, "maxItems": 100 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The tools the agent may call, null when all tools are enabled (including any the server adds later), or \"hidden\" when the caller lacks edit access to the agent." }, "run_tools_automatically": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Whether read tool calls run without a confirmation step." }, "write": { "type": "boolean", "description": "Whether write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": ["read", "write"], "description": "Whether read / write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": [ "type", "name", "account", "enabled_tools", "run_tools_automatically" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana", "box", "browser", "calendar", "computer", "confluence", "cursor", "files", "fs", "github", "gmail", "google_calendar", "google_drive", "google_drive_oauth", "gtm", "helpdocs", "images", "jira", "linear", "mail", "marketplace", "memory", "microsoft_teams", "outlook", "salesforce", "search", "security", "sharepoint", "skills", "system", "test", "web", "webhooks", "worker", "workers" ], "description": "The connector's machine name (e.g. \"github\", \"google_drive\")." }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider-side account identifier, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "The scopes granted on this target." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] } ] }, "maxItems": 100, "description": "Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions." }, "status": { "type": "string", "enum": ["active", "disabled", "deleted"], "description": "\"active\" when the agent can run; \"disabled\" when it is paused (see pause_reason); \"deleted\" when it has been removed." }, "pause_reason": { "oneOf": [ { "type": "string", "enum": [ "run_limit", "credit_limit", "runaway_credit_usage", "workspace_credit_limit", "failure_limit", "mark_session_failed_autopause", "disabled_from_workspace_settings", "disabled_from_api", "disabled_from_agent_settings", "disabled_due_to_no_members_with_access", "disabled_due_to_lack_of_editors", "disabled_by_notion", "internal_error", "needs_user_review", "tool_unavailable" ], "description": "One of: `run_limit`, `credit_limit`, `runaway_credit_usage`, `workspace_credit_limit`, `failure_limit`, `mark_session_failed_autopause`, `disabled_from_workspace_settings`, `disabled_from_api`, `disabled_from_agent_settings`, `disabled_due_to_no_members_with_access`, `disabled_due_to_lack_of_editors`, `disabled_by_notion`, `internal_error`, `needs_user_review`, `tool_unavailable`" }, { "type": "null" } ], "description": "Why the agent is paused when status is \"disabled\" (e.g. \"credit_limit\", \"disabled_from_workspace_settings\"); null when active." }, "created_by": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["user", "bot"], "description": "One of: `user`, `bot`" }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the user or bot that created this agent." } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "null" } ] }, "agent_version": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the published artifact." }, "number": { "type": "number", "description": "The version number." }, "published_at": { "type": "string", "description": "The ISO 8601 timestamp when this version was published." } }, "additionalProperties": false, "required": ["id", "number", "published_at"] }, { "type": "null" } ] }, "created_time": { "type": "string", "format": "date-time", "description": "Date and time when this agent was created." }, "last_edited_time": { "type": "string", "format": "date-time", "description": "Date and time when this agent was last edited." }, "last_run_at": { "oneOf": [ { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T" }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the agent's most recent run, null if it has never run, or \"hidden\" when the caller lacks edit access to the agent." }, "credit_limit": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The per-agent credit limit that applies to this agent, null when uncapped, or \"hidden\" when the caller lacks full access to the agent. This is the effective limit computed at runtime, folding in both the agent's own limit and any workspace-admin default." }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine trigger type (e.g. \"notion.agent.mentioned\", \"recurrence\", \"slack.reaction.added\")." }, "enabled": { "type": "boolean", "description": "Whether this trigger is currently enabled." }, "schedule": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized cadence for recurrence triggers, or null for other trigger types." } }, "additionalProperties": false, "required": ["type", "enabled", "schedule"] }, "maxItems": 100, "description": "The agent's configured triggers, each with a machine type, an enabled flag, and a normalized recurrence schedule when applicable." } }, "additionalProperties": false, "required": [ "object", "id", "agent_type", "name", "description", "instructions_page_id", "icon", "model", "model_mode", "connections", "status", "pause_reason", "created_by", "agent_version", "created_time", "last_edited_time", "last_run_at", "credit_limit", "triggers" ] }, { "type": "object", "properties": { "object": { "type": "string", "const": "agent", "description": "Always `agent`" }, "id": { "type": "string", "const": "33333333-3333-3333-3333-333333333333", "description": "Always `33333333-3333-3333-3333-333333333333`" }, "agent_type": { "type": "string", "const": "notion_ai", "description": "Always `notion_ai`" }, "name": { "type": "string", "const": "Notion Agent", "description": "Always `Notion Agent`" }, "description": { "type": "null" }, "instructions_page_id": { "type": "null" }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/pageIconResponse" }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_agent_avatar", "description": "Type of icon. In this case, a custom agent avatar." }, "custom_agent_avatar": { "type": "object", "properties": { "static_url": { "type": "string", "description": "The URL of the static custom agent avatar." }, "animated_url": { "type": "string", "description": "The URL of the animated custom agent avatar." } }, "additionalProperties": false, "required": [ "static_url", "animated_url" ], "description": "The static and animated URLs for the agent avatar." } }, "additionalProperties": false, "required": ["type", "custom_agent_avatar"] } ] }, "model": { "type": "null" }, "model_mode": { "type": "string", "const": "auto", "description": "Always `auto`" }, "connections": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "notion", "description": "Always `notion`" }, "name": { "type": "string" }, "account": { "type": "null" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Always `page`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "database_property", "description": "Always `database_property`" }, "data_source_id": { "type": "string" }, "property_id": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "data_source_id", "property_id" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "agent", "description": "Always `agent`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "workspace", "description": "Always `workspace`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "owner_private_pages", "description": "Always `owner_private_pages`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "web_search", "description": "Always `web_search`" }, "allowed_domains": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Domains web search is restricted to, or null when unrestricted." } }, "additionalProperties": false, "required": [ "type", "allowed_domains" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "notion_help_docs_search", "description": "Always `notion_help_docs_search`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Content roles (\"reader\" | \"comment_only\" | \"read_and_write\" | \"editor\") for scoped targets, or search verbs (\"allow\" | \"disallow\") for the search targets." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack", "description": "Always `slack`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "slack_workspace", "description": "Always `slack_workspace`" }, "team_id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "team_id"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The linked Slack workspace, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "slack_channel", "description": "Always `slack_channel`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack_all_public_channels", "description": "Always `slack_all_public_channels`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "slack_all_channels", "description": "Always `slack_all_channels`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Slack verbs granted on this target (\"read\" | \"write\" | \"reply_in_thread\" | \"react\")." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "discord", "description": "Always `discord`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "discord_server", "description": "Always `discord_server`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The linked Discord server, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "discord_channel", "description": "Always `discord_channel`" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "discord_all_channels", "description": "Always `discord_all_channels`" } }, "additionalProperties": false, "required": ["type"] } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Discord verbs granted on this target (\"read\" | \"write\" | \"reply_in_thread\" | \"react\")." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_host": { "type": "string", "description": "The MCP server host (never the full URL, which can carry credentials or private path components)." } }, "additionalProperties": false, "required": [ "type", "server_host" ] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The MCP server host, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "enabled_tools": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["name", "title"] }, "maxItems": 100 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The tools the agent may call, null when all tools are enabled (including any the server adds later), or \"hidden\" when the caller lacks edit access to the agent." }, "run_tools_automatically": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Whether read tool calls run without a confirmation step." }, "write": { "type": "boolean", "description": "Whether write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": ["read", "write"], "description": "Whether read / write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": [ "type", "name", "account", "enabled_tools", "run_tools_automatically" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_mcp_server", "description": "Always `custom_mcp_server`" }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "mcp_server", "description": "Always `mcp_server`" }, "server_host": { "type": "string", "description": "The MCP server host (never the full URL, which can carry credentials or private path components)." } }, "additionalProperties": false, "required": [ "type", "server_host" ] }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The MCP server host, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "enabled_tools": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": ["name", "title"] }, "maxItems": 100 }, { "type": "string", "const": "hidden", "description": "Always `hidden`" }, { "type": "null" } ], "description": "The tools the agent may call, null when all tools are enabled (including any the server adds later), or \"hidden\" when the caller lacks edit access to the agent." }, "run_tools_automatically": { "type": "object", "properties": { "read": { "type": "boolean", "description": "Whether read tool calls run without a confirmation step." }, "write": { "type": "boolean", "description": "Whether write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": ["read", "write"], "description": "Whether read / write tool calls run without a confirmation step." } }, "additionalProperties": false, "required": [ "type", "name", "account", "enabled_tools", "run_tools_automatically" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana", "box", "browser", "calendar", "computer", "confluence", "cursor", "files", "fs", "github", "gmail", "google_calendar", "google_drive", "google_drive_oauth", "gtm", "helpdocs", "images", "jira", "linear", "mail", "marketplace", "memory", "microsoft_teams", "outlook", "salesforce", "search", "security", "sharepoint", "skills", "system", "test", "web", "webhooks", "worker", "workers" ], "description": "The connector's machine name (e.g. \"github\", \"google_drive\")." }, "name": { "type": "string" }, "account": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider-side account identifier, null when none is linked, or \"hidden\" when the caller lacks edit access to the agent." }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "additionalProperties": false, "required": ["type", "id"] }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "The scopes granted on this target." } }, "additionalProperties": false, "required": ["target", "scopes"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "name", "account", "permissions" ] } ] }, "maxItems": 100 }, "status": { "type": "string", "const": "active", "description": "Always `active`" }, "pause_reason": { "type": "null" }, "created_by": { "type": "null" }, "agent_version": { "type": "null" }, "created_time": { "type": "null" }, "last_edited_time": { "type": "null" }, "last_run_at": { "type": "null" }, "credit_limit": { "type": "null" }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine trigger type (e.g. \"notion.agent.mentioned\", \"recurrence\", \"slack.reaction.added\")." }, "enabled": { "type": "boolean", "description": "Whether this trigger is currently enabled." }, "schedule": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized cadence for recurrence triggers, or null for other trigger types." } }, "additionalProperties": false, "required": ["type", "enabled", "schedule"] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "object", "id", "agent_type", "name", "description", "instructions_page_id", "icon", "model", "model_mode", "connections", "status", "pause_reason", "created_by", "agent_version", "created_time", "last_edited_time", "last_run_at", "credit_limit", "triggers" ] } ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "title": "Cursor", "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/sessions/{session_id}/events/query": { "post": { "summary": "Query session events", "operationId": "query-session-events", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the session whose events should be queried." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": ["property", "event_type"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": ["property", "number"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": ["property", "event_type"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": ["property", "number"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": ["property", "number"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": [ "property", "number" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": [ "property", "number" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } } ] } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": ["property", "number"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": [ "property", "number" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": [ "property", "number" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } } ] } } } } ] } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": ["property", "event_type"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": ["property", "number"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": ["property", "number"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": [ "property", "number" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": [ "property", "number" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } } ] } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": ["property", "number"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": [ "property", "number" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": "string" } } } } }, { "type": "object", "required": [ "property", "event_type" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["type"] }, "event_type": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] }, "in": { "type": "array", "items": { "type": "string", "enum": [ "user.message", "agent.message", "agent.thinking", "agent.tool_use", "agent.tool_result", "session.status" ] } } } } } }, { "type": "object", "required": [ "property", "number" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["sequence"] }, "number": { "type": "object", "additionalProperties": false, "properties": { "greater_than": { "type": "number" }, "greater_than_or_equal_to": { "type": "number" }, "less_than": { "type": "number" }, "less_than_or_equal_to": { "type": "number" } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["created_at"] }, "timestamp": { "type": "object", "additionalProperties": false, "properties": { "equals": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "after": { "type": "string", "format": "date-time" }, "on_or_before": { "type": "string", "format": "date-time" }, "on_or_after": { "type": "string", "format": "date-time" } } } } } ] } } } } ] } } } } ] } } } } ], "description": "A session event property filter, or an and/or compound filter nested up to three levels deep." }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string", "enum": ["sequence", "created_at"], "description": "One of: `sequence`, `created_at`" }, "direction": { "type": "string", "enum": ["ascending", "descending"], "description": "One of: `ascending`, `descending`" } }, "required": ["property", "direction"] }, "maxItems": 2, "minItems": 1, "description": "Ordered sort precedence. Defaults to sequence ascending." }, "start_cursor": { "type": "string", "description": "The continuation cursor returned by the previous page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of events to return. Maximum: 100." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "session_event", "description": "Always `session_event`" }, "session_event": { "type": "object", "properties": {}, "additionalProperties": false }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "session_event", "description": "Always `session_event`" }, "id": { "type": "string" }, "session_id": { "type": "string" }, "sequence": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string" }, "type": { "type": "string", "const": "user.message", "description": "Always `user.message`" }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Always `text`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "file", "description": "Always `file`" }, "name": { "type": "string" }, "content_type": { "type": "string" }, "url": { "type": "string" }, "expiry_time": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "name", "content_type", "url" ] } ] } }, "created_by": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["user", "bot"], "description": "One of: `user`, `bot`" } }, "additionalProperties": false, "required": ["id", "type"] }, { "type": "null" } ] }, "metadata": { "type": "null" } }, "additionalProperties": false, "required": [ "object", "id", "session_id", "sequence", "created_at", "type", "content", "created_by", "metadata" ] }, { "type": "object", "properties": { "object": { "type": "string", "const": "session_event", "description": "Always `session_event`" }, "id": { "type": "string" }, "session_id": { "type": "string" }, "sequence": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string" }, "type": { "type": "string", "const": "agent.message", "description": "Always `agent.message`" }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Always `text`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "file", "description": "Always `file`" }, "name": { "type": "string" }, "content_type": { "type": "string" }, "url": { "type": "string" }, "expiry_time": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "name", "content_type", "url" ] } ] } }, "created_by": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["user", "bot"], "description": "One of: `user`, `bot`" } }, "additionalProperties": false, "required": ["id", "type"] }, { "type": "null" } ] }, "metadata": { "oneOf": [ { "type": "object", "properties": { "model": { "type": "string" } }, "additionalProperties": false, "required": ["model"] }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "id", "session_id", "sequence", "created_at", "type", "content", "created_by", "metadata" ] }, { "type": "object", "properties": { "object": { "type": "string", "const": "session_event", "description": "Always `session_event`" }, "id": { "type": "string" }, "session_id": { "type": "string" }, "sequence": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string" }, "type": { "type": "string", "const": "agent.thinking", "description": "Always `agent.thinking`" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Always `text`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] } } }, "additionalProperties": false, "required": [ "object", "id", "session_id", "sequence", "created_at", "type", "content" ] }, { "type": "object", "properties": { "object": { "type": "string", "const": "session_event", "description": "Always `session_event`" }, "id": { "type": "string" }, "session_id": { "type": "string" }, "sequence": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string" }, "type": { "type": "string", "const": "agent.tool_use", "description": "Always `agent.tool_use`" }, "tool_name": { "type": "string" } }, "additionalProperties": false, "required": [ "object", "id", "session_id", "sequence", "created_at", "type", "tool_name" ] }, { "type": "object", "properties": { "object": { "type": "string", "const": "session_event", "description": "Always `session_event`" }, "id": { "type": "string" }, "session_id": { "type": "string" }, "sequence": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string" }, "type": { "type": "string", "const": "agent.tool_result", "description": "Always `agent.tool_result`" }, "tool_use_id": { "type": "string" }, "tool_name": { "type": "string" }, "is_error": { "type": "boolean" } }, "additionalProperties": false, "required": [ "object", "id", "session_id", "sequence", "created_at", "type", "tool_use_id", "tool_name", "is_error" ] }, { "type": "object", "properties": { "object": { "type": "string", "const": "session_event", "description": "Always `session_event`" }, "id": { "type": "string" }, "session_id": { "type": "string" }, "sequence": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string" }, "type": { "type": "string", "const": "session.status", "description": "Always `session.status`" }, "status": { "type": "string", "enum": [ "requires_action", "completed", "failed", "canceled", "terminated" ], "description": "One of: `requires_action`, `completed`, `failed`, `canceled`, `terminated`" }, "required_actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["approve", "reject"], "description": "One of: `approve`, `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["action_id", "title", "options"] } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false, "required": ["code", "message", "retryable"] } }, "additionalProperties": false, "required": [ "object", "id", "session_id", "sequence", "created_at", "type", "status" ] } ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "title": "Cursor", "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "session_event", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/sessions/query": { "post": { "summary": "Query sessions", "operationId": "query-sessions", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 2000, "description": "A case-insensitive substring search over session titles." }, "filter": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": ["created_at", "updated_at"] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "maxItems": 100, "description": "Return sessions that match every child filter.", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": ["created_at", "updated_at"] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "maxItems": 100, "description": "Return sessions that match every child filter.", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "maxItems": 100, "description": "Return sessions that match any child filter.", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } } ] } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "maxItems": 100, "description": "Return sessions that match any child filter.", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": ["created_at", "updated_at"] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "maxItems": 100, "description": "Return sessions that match every child filter.", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "maxItems": 100, "description": "Return sessions that match any child filter.", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } } ] } } } } ] } } } } ], "description": "A session property filter, or an and/or compound filter nested up to two levels deep." }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string", "enum": ["created_at", "updated_at"], "description": "One of: `created_at`, `updated_at`" }, "direction": { "type": "string", "enum": ["ascending", "descending"], "description": "One of: `ascending`, `descending`" } }, "required": ["property", "direction"] }, "maxItems": 2, "minItems": 1, "description": "Ordered sort precedence. Defaults to updated_at descending." }, "start_cursor": { "type": "string", "description": "The continuation cursor returned by the previous page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of sessions to return. Maximum: 100." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "session", "description": "Always `session`" }, "session": { "type": "object", "properties": {}, "additionalProperties": false }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "session", "description": "Always `session`" }, "id": { "type": "string" }, "agent_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ], "description": "One of: `queued`, `in_progress`, `requires_action`, `completed`, `failed`, `canceled`, `terminated`" }, "created_by": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["user", "bot"], "description": "One of: `user`, `bot`" } }, "additionalProperties": false, "required": ["id", "type"] }, "agent_version": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer", "minimum": 1 }, "published_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": ["id", "number", "published_at"] }, { "type": "null" } ] }, "models": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "auto", "description": "Always `auto`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "pinned", "description": "Always `pinned`" }, "ids": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "additionalProperties": false, "required": ["type", "ids"] } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "required_actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["approve", "reject"], "description": "One of: `approve`, `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["action_id", "title", "options"] } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false, "required": ["code", "message", "retryable"] }, "trigger_type": { "type": "string" }, "type_labels": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "chat_user_emails": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tool_types": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tool_call_count": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "credits_used": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "runs_completed": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "message_count": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "id", "agent_id", "title", "status", "created_by", "agent_version", "models", "created_at", "updated_at" ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "session", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } }, "x-notion-docs-ref": "https://developers.notion.com/reference/internal/query-sessions" } }, "/v1/threads/{thread_id}/messages/query": { "post": { "summary": "Query thread messages", "operationId": "query-thread-messages", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the thread." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verbose": { "type": "boolean", "description": "Whether to include thinking, raw tool names, tool calls, and tool results. Defaults to false." }, "start_cursor": { "type": "string", "description": "Opaque continuation cursor from the previous page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of messages to return. Maximum: 100." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "thread_message", "description": "Always `thread_message`" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "thread_message", "description": "Always `thread_message`" }, "id": { "$ref": "#/components/schemas/idResponse" }, "role": { "type": "string", "enum": ["user", "agent"], "description": "One of: `user`, `agent`" }, "content": { "type": "string" }, "created_time": { "type": "string", "format": "date-time", "description": "Date and time when this message was created." }, "parent": { "type": "object", "properties": { "type": { "type": "string", "const": "thread", "description": "The parent type." }, "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the parent thread." } }, "additionalProperties": false, "required": ["type", "id"] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "content_type": { "type": "string" }, "url": { "type": "string" }, "expiry_time": { "type": "string", "format": "date-time", "description": "The time when the attachment URL will expire." } }, "additionalProperties": false, "required": ["name", "content_type", "url"] }, "maxItems": 100 }, "content_parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Always `text`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "thinking", "description": "Always `thinking`" }, "text": { "type": "string" } }, "additionalProperties": false, "required": ["type", "text"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "tool_call", "description": "Always `tool_call`" }, "tool_call_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_name": { "type": "string" }, "input": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "agent_step_id": { "oneOf": [ { "$ref": "#/components/schemas/idResponse" }, { "type": "null" } ] }, "tool_call_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_name": { "type": "string" }, "tool_type": { "type": "string" }, "state": { "type": "string" }, "input": { "oneOf": [ {}, { "type": "null" } ] }, "output": { "oneOf": [ {}, { "type": "null" } ] }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "started_at": { "type": "integer", "minimum": 0 }, "finished_at": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "duration_ms": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "id", "agent_step_id", "tool_call_id", "tool_name", "tool_type", "state", "input", "output", "error", "started_at", "finished_at", "duration_ms" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "type", "tool_call_id", "tool_name", "input" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "follow_ups", "description": "Always `follow_ups`" }, "follow_ups": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false, "required": ["label", "message"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type", "follow_ups"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom_agent_template_picker", "description": "Always `custom_agent_template_picker`" } }, "additionalProperties": false, "required": ["type"] } ] }, "maxItems": 100 }, "pending_user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "type": { "type": "string", "const": "tool_confirmation", "description": "Always `tool_confirmation`" }, "title": { "type": "string" }, "requirements": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "general", "description": "Always `general`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "manage_workers", "description": "Always `manage_workers`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "url_safety", "description": "Always `url_safety`" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "required_by_workspace_policy": { "type": "boolean" } }, "additionalProperties": false, "required": ["type", "urls"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "permission_escalation", "description": "Always `permission_escalation`" }, "destination_title": { "type": "string" }, "source_titles": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "delete_content", "description": "Always `delete_content`" }, "page_count": { "type": "integer", "minimum": 0 }, "database_count": { "type": "integer", "minimum": 0 }, "meeting_notes_block_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "type", "page_count", "database_count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "connect_integration", "description": "Always `connect_integration`" }, "integration_type": { "type": "string" }, "integration_name": { "type": "string" }, "handoff_url": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "integration_type", "integration_name", "handoff_url" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_mode", "description": "Always `admin_mode`" }, "explanation": { "type": "string" } }, "additionalProperties": false, "required": ["type"] } ], "title": "Pending user action requirement" }, "maxItems": 100 }, "options": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "const": "approve", "description": "Always `approve`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "reject", "description": "Always `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "use_connection", "description": "Always `use_connection`" }, "label": { "type": "string" }, "input": { "type": "object", "properties": { "type": { "type": "string", "const": "connection_id", "description": "Always `connection_id`" }, "required": { "type": "boolean", "const": true, "description": "Always `true`" } }, "additionalProperties": false, "required": ["type", "required"] } }, "additionalProperties": false, "required": ["id", "label", "input"] } ], "title": "Pending user action option" }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "id", "type", "title", "requirements", "options" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "object", "id", "role", "content", "created_time", "parent" ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "title": "Cursor", "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/agents/{agent_id}/threads/query": { "post": { "summary": "Query threads", "operationId": "query-threads", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent. Use a UUID for custom agents or `notion_ai` for Notion Agent (personal agent); the reserved UUID `33333333-3333-3333-3333-333333333333` remains supported for backward compatibility." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search thread titles." }, "filter": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idRequest", "description": "Filter threads by ID (exact match)." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "all", "pending", "in_progress", "failed", "success" ], "description": "One of: `all`, `pending`, `in_progress`, `failed`, `success`" }, "maxItems": 100, "minItems": 1, "description": "Filter by one or more activity statuses. `all` cannot be combined with another status." }, "created_by": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "me", "description": "Always `me`" } ] }, "maxItems": 100, "minItems": 1, "description": "Filter by creator IDs or \"me\"." }, "last_used_by": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "me", "description": "Always `me`" } ] }, "maxItems": 100, "minItems": 1, "description": "Filter by last-used actor IDs or \"me\"." }, "message_time": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "Inclusive start of the message time window. Defaults to the Unix epoch." }, "end": { "type": "string", "format": "date-time", "description": "Exclusive end of the message time window. Defaults to the current time." } }, "description": "Filter to threads containing a public-facing message in the requested time window." } }, "description": "Thread filters." }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "enum": ["created_time", "last_used_time"], "description": "Timestamp used to sort threads." }, "direction": { "type": "string", "enum": ["ascending", "descending"], "description": "Sort direction." } }, "required": ["timestamp", "direction"] }, "maxItems": 2, "minItems": 1, "description": "Ordered sort precedence. Defaults to last_used_time descending." }, "start_cursor": { "type": "string", "description": "Opaque continuation cursor from the previous page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of threads to return. Maximum: 100." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`" }, "type": { "type": "string", "const": "thread", "description": "Always `thread`" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "thread", "description": "Always `thread`" }, "id": { "$ref": "#/components/schemas/idResponse" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "requires_action", "completed", "failed" ], "description": "One of: `pending`, `requires_action`, `completed`, `failed`" }, "created_time": { "type": "string", "format": "date-time", "description": "Date and time when this thread was created." }, "last_edited_time": { "type": "string", "format": "date-time", "description": "Date and time when this thread was last updated." }, "created_by": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the actor that created this thread: a bot for an integration-created thread, a user for one created in the Notion app." }, "type": { "type": "string", "enum": ["bot", "user"], "description": "The creator type. Threads a caller can see because it has access to the agent, such as a trigger's runs or a teammate's chats, may be created by either a bot or a user." } }, "additionalProperties": false, "required": ["id", "type"] }, "agent_version": { "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse", "description": "The ID of the published artifact." }, "number": { "type": "number", "description": "The version number." }, "published_at": { "type": "string", "description": "The ISO 8601 timestamp when this version was published." } }, "additionalProperties": false, "required": ["id", "number", "published_at"] }, { "type": "null" } ] }, "models": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "auto", "description": "Always `auto`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "pinned", "description": "Always `pinned`" }, "ids": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "maxItems": 100, "description": "The public model this thread is pinned to (e.g. \"claude-sonnet-5\"), with null for a pre-release / early-access model. Empty when the thread has no model recorded yet. Reflects the thread's configuration at creation, so a model changed mid-conversation is not reflected here." } }, "additionalProperties": false, "required": ["type", "ids"] } ] }, "error": { "type": "string" }, "trigger_type": { "type": "string", "description": "How this thread started: the type of the trigger that ran it, or \"chat\"." }, "type_labels": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Labels describing how the thread ran (triggered, chat, setup). Null when the caller lacks edit access to the agent." }, "chat_user_emails": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Emails of the users who participated in this thread. Null when the caller lacks edit access to the agent." }, "tool_types": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Types of tool this thread called. Null when the caller lacks edit access to the agent." }, "tool_call_count": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Number of tool calls in this thread. Null when the caller lacks edit access to the agent." }, "credits_used": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Premium AI credits this thread consumed. Null when the caller lacks edit access to the agent." }, "runs_completed": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Runs completed in this thread. Null when the caller lacks edit access to the agent, or when the thread predates run tracking." }, "pending_user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/idResponse" }, "type": { "type": "string", "const": "tool_confirmation", "description": "Always `tool_confirmation`" }, "title": { "type": "string" }, "requirements": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "general", "description": "Always `general`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "manage_workers", "description": "Always `manage_workers`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "url_safety", "description": "Always `url_safety`" }, "urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "required_by_workspace_policy": { "type": "boolean" } }, "additionalProperties": false, "required": ["type", "urls"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "permission_escalation", "description": "Always `permission_escalation`" }, "destination_title": { "type": "string" }, "source_titles": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "delete_content", "description": "Always `delete_content`" }, "page_count": { "type": "integer", "minimum": 0 }, "database_count": { "type": "integer", "minimum": 0 }, "meeting_notes_block_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "type", "page_count", "database_count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "connect_integration", "description": "Always `connect_integration`" }, "integration_type": { "type": "string" }, "integration_name": { "type": "string" }, "handoff_url": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "integration_type", "integration_name", "handoff_url" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_mode", "description": "Always `admin_mode`" }, "explanation": { "type": "string" } }, "additionalProperties": false, "required": ["type"] } ], "title": "Pending user action requirement" }, "maxItems": 100 }, "options": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "const": "approve", "description": "Always `approve`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "reject", "description": "Always `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, { "type": "object", "properties": { "id": { "type": "string", "const": "use_connection", "description": "Always `use_connection`" }, "label": { "type": "string" }, "input": { "type": "object", "properties": { "type": { "type": "string", "const": "connection_id", "description": "Always `connection_id`" }, "required": { "type": "boolean", "const": true, "description": "Always `true`" } }, "additionalProperties": false, "required": ["type", "required"] } }, "additionalProperties": false, "required": ["id", "label", "input"] } ], "title": "Pending user action option" }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "id", "type", "title", "requirements", "options" ] }, "maxItems": 100 } }, "additionalProperties": false, "required": [ "object", "id", "title", "status", "created_time", "last_edited_time", "created_by", "agent_version", "models" ] }, "maxItems": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "oneOf": [ { "title": "Cursor", "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "type", "results", "has_more", "next_cursor" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/groups/{group_id}/members/users/{user_id}": { "delete": { "summary": "Remove a group member", "operationId": "remove-group-member", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the group." } }, { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the user." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/groupMembershipObjectResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } }, "patch": { "summary": "Update a group member", "operationId": "update-group-member", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the group." } }, { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the user." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["owner", "member"], "description": "The user's new role in the group." } }, "required": ["role"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/groupMembershipObjectResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/pages/{page_id}/remove_guests": { "post": { "summary": "Remove guests from a page", "operationId": "remove-page-guest", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the page to remove guests from." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/partialPageObjectResponse" }, { "$ref": "#/components/schemas/pageObjectResponse" } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/sessions/{session_id}": { "get": { "summary": "Retrieve a session", "operationId": "retrieve-session", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the session to retrieve." } }, { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "session", "description": "Always `session`" }, "id": { "type": "string" }, "agent_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ], "description": "One of: `queued`, `in_progress`, `requires_action`, `completed`, `failed`, `canceled`, `terminated`" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["user", "bot"], "description": "One of: `user`, `bot`" } }, "additionalProperties": false, "required": ["id", "type"] }, "agent_version": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer", "minimum": 1 }, "published_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": ["id", "number", "published_at"] }, { "type": "null" } ] }, "models": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "auto", "description": "Always `auto`" } }, "additionalProperties": false, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "pinned", "description": "Always `pinned`" }, "ids": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "additionalProperties": false, "required": ["type", "ids"] } ] }, "required_actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["approve", "reject"], "description": "One of: `approve`, `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["action_id", "title", "options"] } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false, "required": ["code", "message", "retryable"] }, "trigger_type": { "type": "string" }, "type_labels": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "chat_user_emails": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tool_types": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tool_call_count": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "credits_used": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "runs_completed": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "message_count": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "object", "id", "agent_id", "title", "status", "created_at", "updated_at", "created_by", "agent_version", "models" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/tools/run/internal": { "post": { "summary": "Run an internal tool", "operationId": "run-internal-tool", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "string", "minLength": 1, "description": "Stable connection ID returned by the connections endpoint." }, "action": { "type": "string", "minLength": 1, "description": "Action name returned for the selected connection." }, "args": { "type": "object", "additionalProperties": {}, "description": "Arguments passed to the selected connection action." } }, "required": ["connection", "action"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "description": "The connection action result." } }, "additionalProperties": false, "required": ["result"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/rollout/minimal": { "post": { "summary": "Run a minimal rollout", "operationId": "run-minimal-rollout", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Minimal harness-independent agent input, discriminated by `kind`. The `harness` field selects which agent execution stack runs it.", "oneOf": [ { "type": "object", "required": ["kind", "prompt", "actorId"], "description": "A fresh first-turn user prompt.", "properties": { "kind": { "type": "string", "enum": ["user-input"] }, "prompt": { "type": "string", "description": "Free-text prompt to run as a fresh user-input agent request." }, "workflowId": { "type": "string", "description": "Custom-agent workflow ID. Omit to target the personal agent or supply to target a custom agent." }, "currentPageId": { "type": "string", "description": "Optional page block ID the user is viewing when invoking the agent." }, "actorId": { "type": "string", "description": "Notion user ID to run the agent as. Must be a member of the API token's workspace." }, "promptFormat": { "type": "string", "enum": ["markdownVNext", "plainText"], "description": "How `prompt` is interpreted. `markdownVNext` (default) parses Notion Markdown vNext, turning `` references into structured mentions on every harness; `plainText` uses the prompt verbatim (use for replaying logged user text)." }, "harness": { "type": "string", "enum": ["legacy", "agentService"], "description": "Agent execution harness. `legacy` runs through runInferenceTranscript; `agentService` runs through AgentService. Defaults to `legacy`." }, "execution": { "type": "object", "description": "Execution config with common fields and nested harness-specific options. Fields a harness cannot honor fail with a validation error instead of silently diverging.", "properties": { "model": { "type": "string", "description": "Notion agent model name for the main agent." }, "subagentModel": { "type": "string", "description": "Model for spawned subagents. Legacy harness only today." }, "reasoningEffort": { "type": "string", "description": "Reasoning effort for the selected model." }, "toolPolicy": { "type": "string", "enum": ["auto", "readOnly"], "description": "`auto` (default) runs tools without pausing for confirmation; `readOnly` disables mutations (legacy harness only today)." }, "timeoutMs": { "type": "number", "description": "Overall run timeout in milliseconds." }, "harnessOptions": { "type": "object", "description": "Harness-specific execution options.", "properties": { "evalSession": { "type": "boolean", "description": "Enable a local AgentService internal-MCP eval session. Writes are captured instead of persisted, and later tool calls read prior writes. Supported only for personal-agent runs on the `agentService` harness under `--env local`." } } } } }, "response": { "type": "object", "description": "Response shaping options.", "properties": { "raw": { "type": "boolean", "description": "Include `metadata.raw` in the response: the harness-specific generated request (`raw.input`) and native output (`raw.output`) as JSON. Shapes intentionally vary by harness." }, "operations": { "type": "boolean", "description": "Include `metadata.operations`: every Notion operation captured in commit order. Requires the `agentService` harness and `execution.harnessOptions.evalSession: true`. Defaults to false." } } } }, "additionalProperties": true }, { "type": "object", "required": [ "kind", "workflowId", "triggerId", "triggerData" ], "description": "A triggered custom-agent run. Runs on the legacy harness; agentService support is pending.", "properties": { "kind": { "type": "string", "enum": ["agent-trigger"] }, "workflowId": { "type": "string", "description": "Custom-agent workflow ID owning the trigger." }, "triggerId": { "type": "string", "description": "Trigger ID defined on the workflow." }, "triggerData": { "type": "object", "description": "Trigger variables for the run." }, "harness": { "type": "string", "enum": ["legacy", "agentService"], "description": "Agent execution harness. `legacy` runs through runInferenceTranscript; `agentService` runs through AgentService. Defaults to `legacy`." }, "execution": { "type": "object", "description": "Execution config with common fields and nested harness-specific options. Fields a harness cannot honor fail with a validation error instead of silently diverging.", "properties": { "model": { "type": "string", "description": "Notion agent model name for the main agent." }, "subagentModel": { "type": "string", "description": "Model for spawned subagents. Legacy harness only today." }, "reasoningEffort": { "type": "string", "description": "Reasoning effort for the selected model." }, "toolPolicy": { "type": "string", "enum": ["auto", "readOnly"], "description": "`auto` (default) runs tools without pausing for confirmation; `readOnly` disables mutations (legacy harness only today)." }, "timeoutMs": { "type": "number", "description": "Overall run timeout in milliseconds." }, "harnessOptions": { "type": "object", "description": "Harness-specific execution options.", "properties": { "evalSession": { "type": "boolean", "description": "Enable a local AgentService internal-MCP eval session. Writes are captured instead of persisted, and later tool calls read prior writes. Supported only for personal-agent runs on the `agentService` harness under `--env local`." } } } } }, "response": { "type": "object", "description": "Response shaping options.", "properties": { "raw": { "type": "boolean", "description": "Include `metadata.raw` in the response: the harness-specific generated request (`raw.input`) and native output (`raw.output`) as JSON. Shapes intentionally vary by harness." }, "operations": { "type": "boolean", "description": "Include `metadata.operations`: every Notion operation captured in commit order. Requires the `agentService` harness and `execution.harnessOptions.evalSession: true`. Defaults to false." } } } }, "additionalProperties": true } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The minimal rollout request, echoed verbatim." }, "output": { "type": "string", "description": "Normalized text transcript of the run, identical in shape across harnesses, for side-by-side grading. Empty when the run produced no output." }, "metadata": { "type": "object", "properties": { "harness": { "type": "string", "enum": ["legacy", "agentService"], "description": "The agent execution harness that ran this request." }, "status": { "type": "string", "enum": ["completed", "failed", "error"], "description": "Terminal status of the agent run." }, "threadId": { "type": "string", "description": "ID of the thread created for this run." }, "threadUrl": { "type": "string", "description": "URL of the thread created for this run." }, "traceId": { "type": "string", "description": "Trace ID for this run." }, "errorMessage": { "type": "string", "description": "Error details when status is not `completed`." }, "promptDiagnostics": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Non-fatal notes from markdown vNext prompt parsing. Present only when the parse produced diagnostics." }, "raw": { "type": "object", "properties": { "input": { "description": "Harness-specific generated request; shape varies by harness." }, "output": { "description": "Harness-specific native output; shape varies by harness: merged InferenceTranscriptStep list on the legacy harness, the durable session event log on agentService. Absent when the run produced no native output (e.g. a timeout)." } }, "additionalProperties": false, "required": ["input"], "description": "Harness-native request/output payloads. Present only when requested via `response.raw`." }, "operations": { "type": "array", "items": {}, "description": "Every Notion operation captured in commit order. Present only when requested via `response.operations` for an enabled read-your-writes eval session." } }, "additionalProperties": false, "required": ["harness", "status"], "description": "Run bookkeeping: harness, status, thread/trace ids, errors, and opt-in harness-native payloads under `raw`." } }, "additionalProperties": false, "required": ["input", "output", "metadata"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/rollout/run": { "post": { "summary": "Run a rollout", "operationId": "run-rollout", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["execution"], "properties": { "json": { "description": "Inline rollout JSON payload." }, "braintrustSlug": { "type": "string", "description": "Braintrust source in 'project:dataset:rowId' or 'org:project:dataset:rowId' format." }, "braintrust": { "type": "object", "additionalProperties": true, "properties": { "org": { "type": "string" }, "project": { "type": "string" }, "dataset": { "type": "string" }, "id": { "type": "string" }, "logId": { "type": "string" } } }, "preprocessors": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "response": { "type": "object", "properties": { "input": { "type": "boolean", "description": "Whether to include the original input in the response payload. Defaults to false." }, "originalMetadata": { "type": "boolean", "description": "Whether to include source scenario metadata under metadata.originalMetadata. Defaults to false." } } }, "execution": { "type": "object", "properties": { "agentRunner": { "type": "object", "additionalProperties": true, "properties": { "evalMode": { "type": "string", "enum": ["live", "sandbox", "single-step"] }, "workflowAgentMode": { "type": "string", "enum": ["basic", "all"] }, "startFromLastStepOfType": { "type": "string" }, "contextPageId": { "type": "string" }, "additionalDebugOverrides": { "type": "object", "additionalProperties": true }, "agentModelConfig": { "type": "object", "additionalProperties": true }, "subagentModelConfig": { "type": "object", "additionalProperties": true } } }, "modelConfig": { "type": "object", "additionalProperties": true, "properties": { "notionModelName": { "type": "string" }, "rawVendorOverride": { "type": "object", "additionalProperties": true } } }, "appEnvironment": { "type": "object", "additionalProperties": true, "properties": { "actorId": { "type": "string" }, "createThread": { "type": "boolean" }, "attachmentUrlResolver": { "type": "string", "enum": ["admin", "thread"] } } }, "outputProcessors": { "type": "array", "items": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["formatted"] } } } }, "logging": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["includeRawInferences"] } } }, { "type": "object", "required": ["type", "enabled"], "properties": { "type": { "type": "string", "enum": ["braintrustLogs"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } } } ] } } } } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "description": "Inference output." }, "input": { "description": "Original rollout input. Omitted unless explicitly requested via `response.input`." }, "scores": { "description": "Grader results as name-to-score mappings." }, "metadata": { "description": "Inference metadata. Includes post-processor results, grader debug info, raw inference capture under `metadata.logging.rawInferences`, and `metadata.traceUrl` after a successful opt-in Braintrust logging flush." } }, "additionalProperties": false, "required": ["output"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/tools/run": { "post": { "summary": "Run an AI tool", "operationId": "run-tool", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "search", "description": "The name of the tool to run." }, "search": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Semantic search query over your entire Notion workspace and connected sources\n(Slack, Google Drive, Github, Jira, Microsoft Teams, Sharepoint, OneDrive,\nor Linear). For best results, don't provide more than one question per tool call.\nUse a separate \"search\" tool call for each search you want to perform.\n\nAlternatively, the query can be a substring or keyword to find users by matching\nagainst their name or email address. For example: \"john\" or \"john@example.com\"" }, "query_type": { "type": "string", "enum": ["internal", "user"], "description": "Specify type of the query as either \"internal\" or \"user\". Always include this input if performing\n\"user\" search." }, "content_search_mode": { "type": "string", "enum": ["workspace_search", "ai_search"], "description": "Select search backend: \"workspace_search\" (faster, workspace-only) or \"ai_search\" (semantic, includes Slack/Linear/etc.). If omitted, uses AI search if available. Content searches only." }, "data_source_url": { "type": "string", "description": "Optionally, provide the URL of a Data source to search. This will perform a semantic search over\nthe pages in the Data Source. Note: must be a Data Source, not a Database. tags are\npart of the Notion flavored Markdown format returned by tools like fetch. The full spec is\navailable in the create-pages tool description." }, "page_url": { "type": "string", "description": "Optionally, provide the URL or ID of a page to search within. This will perform a semantic search\nover the content within and under the specified page. Accepts either a full page URL\n(e.g. https://notion.so/workspace/Page-Title-1234567890) or just the page ID (UUIDv4) with or\nwithout dashes." }, "teamspace_id": { "type": "string", "description": "Optionally, provide the ID of a teamspace to restrict search results to. This will perform a search\nover content within the specified teamspace only. Accepts the teamspace ID (UUIDv4) with or\nwithout dashes." }, "filters": { "type": "object", "properties": { "created_date_range": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "The start date of the date range as an ISO 8601 date string, if any." }, "end_date": { "type": "string", "format": "date", "description": "The end date of the date range as an ISO 8601 date string, if any." } }, "description": "Optional filter to only produce search results created within the specified date range." }, "created_by_user_ids": { "type": "array", "items": { "$ref": "#/components/schemas/idRequest" }, "maxItems": 100, "description": "Optional filter to only produce search results created by the Notion users that have the specified user IDs." } }, "description": "Optionally provide filters to apply to the search results. Only valid when query_type is 'internal'." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Maximum number of results to return (default 10). Lower values reduce response size." }, "max_highlight_length": { "type": "integer", "minimum": 0, "maximum": 500, "description": "Maximum character length for result highlights (default 200). Set to 0 to omit highlights entirely." } }, "required": ["query"], "description": "The parameters for the search tool. Search the user's Notion workspace and connected sources (Slack, Google Drive,\n\t\tGitHub, Jira, Teams, SharePoint, OneDrive, Linear) and return a ranked list\n\t\tof results to read. Two query types:\n\t\t- \"internal\" (default): content across Notion and connected sources.\n\t\t- \"user\": find people by name or email.\n\n\t\tWhen to use this vs. get-answer:\n\t\t- Use search when you want results to read, filter, cite, or fetch in full,\n\t\t or when you'll synthesize across sources yourself.\n\t\t- Use get-answer when you just want one synthesized answer and don't need\n\t\t the underlying pages. If its answer isn't good enough, come back to search\n\t\t for the full results.\n\n\t\tHow to search well:\n\t\t- One question or topic per call. Make separate calls for separate needs.\n\t\t- If the question names a person, timeframe, teamspace, or database, pass\n\t\t the matching filter. Otherwise omit filters for the broadest recall.\n\t\t- Date filter values use the YYYY-MM-DD calendar-date format.\n\t\t- Keep responses small: set page_size (default 10, max 25) and\n\t\t max_highlight_length (default 200; 0 to omit) as low as you can.\n\t\t- After finding a Notion result, call fetch with its \"id\" for full contents.\n\n\t\tThe backend is auto-selected: AI search when the user has Notion AI and\n\t\tconnectors, otherwise faster workspace-only search. Use content_search_mode\n\t\tonly when you specifically need one or the other.\n\n\t\tTo search within a database: fetch the database first to get its data source\n\t\tURL (collection://...) from tags, then pass that as\n\t\tdata_source_url. For multi-source databases, match by view ID (?v=...) or\n\t\tsearch each source. Don't combine a database URL or ID with the collection://\n\t\tprefix, and don't use a database URL as page_url.\n\n\t\t\n\t\t{\n\t\t\t\"query\": \"quarterly revenue report\",\n\t\t\t\"query_type\": \"internal\",\n\t\t\t\"filters\": {\n\t\t\t\t\"created_date_range\": {\n\t\t\t\t\t\"start_date\": \"2024-01-01\",\n\t\t\t\t\t\"end_date\": \"2025-01-01\"\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\t\n\n\t\t\n\t\t{\"query\": \"project updates\", \"query_type\": \"internal\", \"teamspace_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"filters\": {\"created_by_user_ids\": [\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"]}}\n\t\t\n\n\t\t\n\t\t{\"query\": \"design review\", \"data_source_url\": \"collection://f336d0bc-b841-465b-8045-024475c079dd\", \"filters\": {\"created_date_range\": {\"start_date\": \"2024-10-01\"}, \"created_by_user_ids\": [\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"b2c3d4e5-f6a7-8901-bcde-f12345678901\"]}}\n\t\t\n\n\t\t\n\t\t{\"query\": \"john@example.com\", \"query_type\": \"user\"}\n\t\t" } }, "required": ["type", "search"], "title": "Search" }, { "type": "object", "properties": { "type": { "type": "string", "const": "fetch", "description": "The name of the tool to run." }, "fetch": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID or URL of the Notion page, database, or data source to fetch. Supports notion.so URLs, Notion Sites URLs (*.notion.site), raw UUIDs, and data source URLs (collection://...). Pass \"self\" to fetch the connected workspace and user identity. Pass a notion://docs/* URI to read that documentation resource." }, "include_transcript": { "type": "boolean", "description": "Whether to include meeting note transcripts. Defaults to false. When true, full transcripts are included; when false, a placeholder with the meeting note URL is shown instead." }, "include_discussions": { "type": "boolean", "description": "Whether to include discussion/comment indicators in the page output. When true, adds a summary with discussion count, preview snippets, and discussion:// URLs. Use with the get_comments tool to retrieve full discussion content. Defaults to false." } }, "required": ["id"], "description": "The parameters for the fetch tool. Retrieves details about a Notion entity (page, database, or data source) by URL or ID.\n\nProvide URL or ID in `id` parameter. Make multiple calls to fetch multiple entities.\n\nPages use enhanced Markdown format. For the complete specification,\nread the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool.\n\nPass a `notion://docs/*` URI (e.g. `notion://docs/enhanced-markdown-spec` or\n`notion://docs/view-dsl-spec`) as the `id` to read that documentation resource through\nthis tool. The content is identical to the MCP resource of the same URI.\n\nDatabases return all data sources (collections). Each data source has a unique ID shown in\n`` tags. You can pass a data source ID directly to this\ntool to fetch details about that specific data source, including its schema and properties.\nUse data source IDs with update_data_source and query_data_sources tools. Multi-source\ndatabases (e.g., with linked sources) will show multiple data sources.\nIf fetching a database block ID returns a validation error, use the `collection://` data source\nURL included in that error instead.\n\nSet `include_discussions` to true to see discussion counts and inline discussion markers\nthat correlate with the `get_comments` tool. The page output will include a\n`` summary tag with discussion count, preview snippets, and\n`discussion://` URLs that match the discussion IDs returned by `get_comments`.\n\nPass the special id `\"self\"` to get the connected workspace and user identity instead of\nan entity. The result includes a `self` object with the workspace id + name and the\nauthenticated user's id, name, and email. Use this to label the connection (e.g. by\nworkspace name) or obtain a stable id for the connected workspace and user.\n\nOn MCP and RunTool surfaces, `self` also includes `current_tool_access`: a map from\ntool names to `available`, `available_with_limit` (calls can be made up to the limit included\nwith the workspace's plan), `upgrade_required`, or `not_enabled`. Entries include an\n`upgrade_url` when a workspace upgrade can change the status. Use this map to identify\nwhether calls are available, plan-limited, upgrade-gated, or disabled.\n\n{\"id\": \"https://notion.so/workspace/Page-a1b2c3d4e5f67890\"}\n{\"id\": \"12345678-90ab-cdef-1234-567890abcdef\"}\n{\"id\": \"https://myspace.notion.site/Page-Title-abc123def456\"}\n{\"id\": \"page-uuid\", \"include_discussions\": true}\n{\"id\": \"collection://12345678-90ab-cdef-1234-567890abcdef\"}\n{\"id\": \"self\"}\n{\"id\": \"notion://docs/enhanced-markdown-spec\"}" } }, "required": ["type", "fetch"], "title": "Fetch" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_attachment", "description": "The name of the tool to run." }, "create_attachment": { "allOf": [ { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "description": "The filename to create in Notion, including a supported extension such as .html, .md, .pdf, or .png. Required with content and source_url. Omit it with source_file_id; the stored upload already carries a filename." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Optional MIME type, such as text/html or application/pdf. It must match the filename extension; omit it to infer the type from the filename. Omit it with source_file_id; the stored upload already carries a content type." } } }, { "oneOf": [ { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "description": "The filename to create in Notion, including a supported extension such as .html, .md, .pdf, or .png. Required with content and source_url. Omit it with source_file_id; the stored upload already carries a filename." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Optional MIME type, such as text/html or application/pdf. It must match the filename extension; omit it to infer the type from the filename. Omit it with source_file_id; the stored upload already carries a content type." }, "content": { "type": "string", "maxLength": 204800, "description": "The complete UTF-8 text content of the file. Maximum 200 KiB after UTF-8 encoding. Requires filename." } }, "required": ["filename", "content"] }, { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "description": "The filename to create in Notion, including a supported extension such as .html, .md, .pdf, or .png. Required with content and source_url. Omit it with source_file_id; the stored upload already carries a filename." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Optional MIME type, such as text/html or application/pdf. It must match the filename extension; omit it to infer the type from the filename. Omit it with source_file_id; the stored upload already carries a content type." }, "source_url": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "A direct, publicly reachable HTTPS URL from which Notion can download the file within one minute. Redirects, private network addresses, custom request headers, and cookies are not supported. Requires filename." } }, "required": ["filename", "source_url"] }, { "type": "object", "properties": { "source_file_id": { "type": "string", "minLength": 1, "maxLength": 36, "description": "The ID of a file upload this exact integration already created, using create_file_upload when available or the Notion File Upload API with this integration's token. Its status must be uploaded." } }, "required": ["source_file_id"] } ] } ], "title": "Create a Notion attachment", "description": "The parameters for the create_attachment tool. Create an attachment and upload it to Notion.\n\nProvide exactly one source:\n- content for small UTF-8 text artifacts such as HTML, Markdown, plain text, CSV, JSON, XML, CSS, YAML, TSV, calendar, GPX, or SVG files.\n- source_url for a file available at a direct, publicly reachable HTTPS URL. This supports binary files and temporary signed download URLs. Notion performs a metadata-only HEAD request when supported, followed by the GET request that downloads the file. The URL must not redirect, require cookies or request headers, or resolve to a private network address.\n- source_file_id for a file this integration already uploaded. When create_file_upload is available, use it for local files so the upload is created by this same MCP integration; otherwise use ntn files create or the Notion File Upload API with this integration's token. Nothing is re-sent or re-downloaded. The upload must have a status of uploaded and must have been created by this exact integration; an upload made with a different token is not visible here.\n\nFor content and source_url, the filename must use a supported extension, and the optional content_type is a MIME type that must agree with the filename; omit it to infer the type from the extension. source_file_id takes neither, because the stored upload already carries both. Inline content is limited to 200 KiB after UTF-8 encoding. URL downloads must complete within one minute and are limited to 5 MiB for free workspaces and 50 MiB for paid workspaces. For local files, use create_file_upload when available. For larger files, URLs that redirect, or authenticated downloads requiring headers, upload through the Notion File Upload API with this integration's token and pass source_file_id.\n\nThe response includes a markdown_source value. To place the uploaded file on a page, pass that source to create-pages or update-page. To attach it to a comment, include suggested_markdown on a separate line in create-comment markdown. Unattached uploads remain temporary and are deleted once they expire: content and source_url open a fresh one-hour window, while source_file_id keeps the window that opened when the file was first uploaded, so place that source promptly and upload the file again if it has already expired. \"HTML\", \"HTML block\", \"HTML artifact\", and \"HTML embed\" all mean an HTML file placed with so Notion renders the sandboxed preview. Never place HTML in a code block or file block. Use for other files.\n\n\n1. Create an HTML artifact: {\"filename\":\"report.html\",\"content\":\"

Report

\"}\n2. Create Markdown with an explicit MIME type: {\"filename\":\"notes.md\",\"content_type\":\"text/markdown\",\"content\":\"# Notes\\n\\nHello\"}\n3. Import a PDF from a signed URL: {\"filename\":\"report.pdf\",\"source_url\":\"https://storage.example.com/report.pdf?signature=...\"}\n4. Reference a file already uploaded by this integration: {\"source_file_id\":\"1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b\"}\n" } }, "required": ["type", "create_attachment"], "title": "Create Attachment" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_file_upload", "description": "The name of the tool to run." }, "create_file_upload": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "description": "The filename to create in Notion, including a supported extension such as .pdf, .png, or .zip." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Optional MIME type, such as application/pdf or image/png. Prefer omitting it so the type is inferred from the filename: a type that disagrees with the extension is stored as given, and the file then renders as the wrong kind." } }, "additionalProperties": false, "required": ["filename"], "description": "The parameters for the create_file_upload tool. Create a short-lived URL for uploading one local file directly to Notion.\n\nAfter calling this tool, send exactly one multipart/form-data POST request to `upload_url`. Put the file in the `file` form field and include every header returned in `upload_headers`. Files are limited to 20 MiB for this single-part upload flow, and workspace file-size limits still apply.\n\nThe upload response includes `markdown_source` and `suggested_markdown`, which can be passed directly to create-pages or update-page, or included on a separate line in create-comment markdown to attach the file. The URL is short-lived, can upload only the FileUpload created by this call, and runs as this same integration.\n\n\n1. Prepare an image upload: {\"filename\":\"diagram.png\"}\n2. Prepare a PDF upload with an explicit MIME type: {\"filename\":\"report.pdf\",\"content_type\":\"application/pdf\"}\n" } }, "required": ["type", "create_file_upload"], "title": "Create File Upload" }, { "type": "object", "properties": { "type": { "type": "string", "const": "download_attachment", "description": "The name of the tool to run." }, "download_attachment": { "type": "object", "properties": { "file_upload_id": { "$ref": "#/components/schemas/idRequest", "description": "The FileUpload ID returned by the create-attachment tool." } }, "required": ["file_upload_id"], "description": "The parameters for the download_attachment tool. Download the contents of a small UTF-8 text attachment created by the Notion MCP `create-attachment` tool.\n\nPass the `file_upload_id` returned by `create-attachment`. The attachment must belong to the requesting integration, have completed uploading, and use a supported text format such as HTML, Markdown, plain text, CSV, JSON, XML, CSS, YAML, TSV, calendar, GPX, or SVG.\n\nThe response contains the complete text in `content` so you can save it locally, edit it, and call `create-attachment` again to upload a new version. Downloads are limited to 200 KiB. This tool does not fetch arbitrary URLs or return binary files. For larger or binary attachments, use the signed file URL returned when reading the containing Notion page.\n\n\n1. Download a text attachment: {\"file_upload_id\":\"12345678-90ab-cdef-1234-567890abcdef\"}\n" } }, "required": ["type", "download_attachment"], "title": "Download Attachment" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_pages", "description": "The name of the tool to run." }, "create_pages": { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] }, "description": "The properties of the new page, which is a JSON map of property names to SQLite values.\nFor pages in a database, use the SQLite schema definition shown in .\nFor pages outside of a database, the only allowed property is \"title\", which is the title of the page and is automatically shown at the top of the page as a large heading." }, "content": { "type": "string", "description": "The content of the new page, using Notion Markdown." }, "template_id": { "type": "string", "description": "The ID of a template to apply to this page. When specified, do not provide 'content' as the template will provide it. Properties can still be set alongside the template. Get template IDs from the section in the fetch tool results." }, "icon": { "type": "string", "description": "An emoji character (e.g. \"🚀\"), a custom emoji by name (e.g. \":rocket_ship:\"), or an external image URL. Use \"none\" to explicitly set no icon. Omit to leave unchanged." }, "cover": { "type": "string", "description": "An external image URL for the page cover. Use \"none\" to explicitly set no cover. Omit to leave unchanged." } }, "additionalProperties": false }, "maxItems": 100, "description": "The pages to create." }, "parent": { "oneOf": [ { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the parent page (with or without dashes), for example, 195de9221179449fab8075a27c979105" }, "type": { "type": "string", "const": "page_id", "description": "Always `page_id`" } }, "required": ["page_id"] }, { "type": "object", "properties": { "database_id": { "type": "string", "description": "The ID of the parent database (with or without dashes), for example, 195de9221179449fab8075a27c979105" }, "type": { "type": "string", "const": "database_id", "description": "Always `database_id`" } }, "required": ["database_id"] }, { "type": "object", "properties": { "data_source_id": { "type": "string", "description": "The ID of the parent data source (collection), with or without dashes. For example, f336d0bc-b841-465b-8045-024475c079dd" }, "type": { "type": "string", "const": "data_source_id", "description": "Always `data_source_id`" } }, "required": ["data_source_id"] } ], "description": "The parent under which the new pages will be created. This can be a page (page_id), a database page (database_id), or a data source/collection under a database (data_source_id). If omitted, the new pages will be created as private pages at the workspace level. Use data_source_id when you have a collection:// URL from the fetch tool." }, "allow_async": { "type": "boolean", "description": "Set to true to opt into receiving an async_task result when this create operation is accepted for background execution. If omitted or false, the tool keeps the existing synchronous result shape." } }, "required": ["pages"], "description": "The parameters for the create_pages tool. ## Overview\n\n\t\tCreates one or more Notion pages, with the specified properties and content.\n\n\t\t## Parent\n\n\t\tAll pages created with a single call to this tool will have the same parent.\n\t\tThe parent can be a Notion page (\"page_id\") or data source (\"data_source_id\").\n\t\tIf the parent is omitted, the pages are created as standalone, workspace-level\n\t\tprivate pages, and the person that created them can organize them later as they\n\t\tsee fit.\n\n\t\tIf you have a database URL, ALWAYS pass it to the \"fetch\" tool first to get the schema\n\t\tand URLs of each data source under the database. You can't use the \"database_id\"\n\t\tparent type if the database has more than one data source, so you'll need to identify\n\t\twhich \"data_source_id\" to use based on the situation and the results from the fetch tool\n\t\t(data source URLs look like collection://).\n\n\t\tIf you know the pages should be created under a data source, do NOT use the database ID\n\t\tor URL under the \"page_id\" parameter; \"page_id\" is only for regular, non-database pages.\n\n\t\t## Content\n\n\t\tNotion page content is a string in Notion-flavored Markdown format.\n\n\t\tDon't include the page title at the top of the page's content. Only include it under\n\t\t\"properties\".\n\n\t\t**IMPORTANT**: For the complete Markdown specification, always first\n\t\tread the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool.\n\t\tDo NOT guess or hallucinate Markdown syntax.\n\t\tThis spec is also applicable to other tools like update-page and fetch.\n\n\t\t## Properties\n\n\t\tNotion page properties are a JSON map of property names to SQLite values.\n\n\t\tWhen creating pages in a database:\n\t\t- Use the correct property names from the data source schema shown in the fetch tool results.\n\t\t- Always include a title property. Data sources always have exactly one title property, but\n\t\t it may not be named \"title\", so, again, rely on the fetched data source schema.\n\n\t\tFor pages outside of a database:\n\t\t- The only allowed property is \"title\",\twhich is the title of the page in inline markdown format.\n\t\t Always include a \"title\" property.\n\n\t\t**IMPORTANT**: Some property types require specific formats:\n\t- Date properties: Split into \"date:{property}:start\", \"date:{property}:end\" (optional), and\n\t \"date:{property}:is_datetime\" (0 or 1)\n\t- Place properties: Split into \"place:{property}:name\", \"place:{property}:address\",\n\t \"place:{property}:latitude\", \"place:{property}:longitude\", and\n\t \"place:{property}:google_place_id\" (optional)\n\t- Number properties: Use JavaScript numbers (not strings)\n\t- Checkbox properties: Use \"__YES__\" for checked, \"__NO__\" for unchecked\n\t- Relation properties: Use an array of related page URLs or page IDs, e.g.\n\t [\"https://www.notion.so/26ab1f9f4c5f80b18d3bd10a6b1d2f4e\", \"26ab1f9f-4c5f-80b1-8d3b-d10a6b1d2f4e\"]\n\t- Files properties: Use a JSON array of file IDs, Notion Folder URLs, and/or tags\n\t copied from fetch output. Folders are stored as native Folder references, not ordinary links.\n\n\t**Special property naming**: Properties named \"id\" or \"url\" (case insensitive) must be\n\tprefixed with \"userDefined:\" (e.g., \"userDefined:URL\", \"userDefined:id\")\n\n\t\t## Templates\n\n\t\tWhen creating a page in a database, you can apply a template to pre-populate it with\n\t\tcontent and property values. Use the \"fetch\" tool on a database to see available\n\t\ttemplates in the section of each data source.\n\n\t\tWhen using a template:\n\t\t- Pass the template's ID as \"template_id\" in the page object.\n\t\t- Do NOT include \"content\" when using a template, as the template provides it.\n\t\t- You can still set \"properties\" alongside the template to override template defaults.\n\t\t- Template application is asynchronous. The page is created immediately but starts\n\t\t blank; the template content will appear shortly after.\n\n\t\t## Icon and Cover\n\n\t\tEach page can optionally have an icon and a cover image.\n\t\t- \"icon\": An emoji character (e.g. \"🚀\"), a custom emoji by name (e.g. \":rocket_ship:\"),\n\t\t or an external image URL. Use \"none\" to remove. Omit to leave unchanged.\n\t\t- \"cover\": An external image URL. Use \"none\" to remove. Omit to leave unchanged.\n\n\t\t## Examples\n\n\t\t\n\t\t{\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"properties\": {\"title\": \"My Page\"},\n\t\t\t\t\t\"icon\": \"🚀\",\n\t\t\t\t\t\"cover\": \"https://example.com/cover.jpg\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"parent\": {\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\"},\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"template_id\": \"a5da15f6-b853-455d-8827-f906fb52db2b\",\n\t\t\t\t\t\"properties\": {\n\t\t\t\t\t\t\"Task Name\": \"New urgent bug\"\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"properties\": {\"title\": \"Page title\"},\n\t\t\t\t\t\"content\": \"# Section 1 {color=\"blue\"}\nSection 1 content\n
\nToggle block\n\tHidden content inside toggle\n
\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"parent\": {\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\"},\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"properties\": {\n\t\t\t\t\t\t\"Task Name\": \"Task 123\",\n\t\t\t\t\t\t\"Status\": \"In Progress\",\n\t\t\t\t\t\t\"Priority\": 5,\n\t\t\t\t\t\t\"Is Complete\": \"__YES__\",\n\t\t\t\t\t\t\"date:Due Date:start\": \"2024-12-25\",\n\t\t\t\t\t\t\"date:Due Date:is_datetime\": 0\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"parent\": {\"page_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"},\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"properties\": {\"title\": \"Page title\"},\n\t\t\t\t\t\"content\": \"# Section 1\n\nSection 1 content\n\n# Section 2\n\nSection 2 content\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t## Async support\n\n\t\tSet \"allow_async\" to true to opt into receiving an async task result when\n\t\tthis create operation is accepted for background execution. If this field\n\t\tis omitted or false, the tool keeps the existing synchronous result shape." } }, "required": ["type", "create_pages"], "title": "Create Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_page", "description": "The name of the tool to run." }, "update_page": { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page to update, with or without dashes." }, "command": { "type": "string", "enum": [ "update_properties", "update_content", "replace_content", "insert_content", "apply_template", "update_verification" ], "description": "The update command to execute." }, "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] }, "description": "Required for \"update_properties\" command. A JSON object that updates the page's properties.\nFor pages in a database, use the SQLite schema definition shown in .\nFor pages outside of a database, the only allowed property is \"title\", which is the title of the page in inline markdown format.\nUse null to remove a property's value." }, "new_str": { "type": "string", "description": "Required for \"replace_content\" command. The new content string to replace the entire page content with." }, "content": { "type": "string", "description": "Required for \"insert_content\" command. The markdown content to insert into the page." }, "content_updates": { "type": "array", "items": { "type": "object", "properties": { "old_str": { "type": "string", "description": "The existing content string to find and replace. Must exactly match the page content." }, "new_str": { "type": "string", "description": "The new content string to replace old_str with." }, "replace_all_matches": { "type": "boolean", "description": "If true, replaces all occurrences of old_str. If false (default), the operation fails if there are multiple matches." } }, "required": ["old_str", "new_str"] }, "maxItems": 100, "description": "Required for \"update_content\" command. An array of search-and-replace operations, each with old_str (content to find) and new_str (replacement content)." }, "position": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "start", "description": "Insert the content at the start of the page." } }, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "end", "description": "Insert the content at the end of the page." } }, "required": ["type"] } ], "description": "Optional for \"insert_content\" command. Use {\"type\":\"start\"} to prepend content or {\"type\":\"end\"} to append content. Omit to append." }, "allow_deleting_content": { "type": "boolean", "description": "Optional for \"replace_content\" and \"update_content\" commands. Set to true to allow deletion of child pages and databases that are not referenced in the new content. If false or omitted, the operation will fail with an error listing the pages/databases that would be deleted." }, "template_id": { "type": "string", "description": "Required for \"apply_template\" command. The ID of a template to apply to this page. Template content is appended to any existing page content." }, "verification_status": { "type": "string", "enum": ["verified", "unverified"], "description": "Required for \"update_verification\" command. Set to \"verified\" to mark the page as verified, or \"unverified\" to remove verification. When updating verification, the owner will be automatically set to the authenticated actor." }, "verification_expiry_days": { "type": "integer", "minimum": 1, "description": "Optional for \"update_verification\" command when verification_status is \"verified\". Number of days until verification expires (e.g. 7, 30, 90). Omit for indefinite verification." }, "icon": { "type": "string", "description": "An emoji character (e.g. \"🚀\"), a custom emoji by name (e.g. \":rocket_ship:\"), or an external image URL. Use \"none\" to remove the icon. Omit to leave unchanged. Can be set alongside any command." }, "cover": { "type": "string", "description": "An external image URL for the page cover. Use \"none\" to remove the cover. Omit to leave unchanged. Can be set alongside any command." }, "is_skill": { "type": "boolean", "description": "Set to true to mark this page as an AI skill, or false to remove the AI skill designation. Can be set alongside any command." }, "allow_async": { "type": "boolean", "description": "Optional. Set to true to opt into an async_task response after the update_page request is validated, durably persisted, and accepted for queued execution. If omitted or false, the tool waits for a synchronous result when possible, but may still return a pollable async_task response if queued execution exceeds the synchronous wait deadline." } }, "required": ["page_id", "command"], "description": "The parameters for the update_page tool. ## Overview\n\n\t\tUpdate a Notion page's properties or content.\n\n\t\t## Properties\n\n\t\tNotion page properties are a JSON map of property names to SQLite values.\n\n\t\tFor pages in a database:\n\t\t- ALWAYS use the \"fetch\" tool first to get the data source schema and the\texact property names.\n\t\t- Provide a non-null value to update a property's value.\n\t\t- Omitted properties are left unchanged.\n\n\t\t**IMPORTANT**: Some property types require specific formats:\n\t- Date properties: Split into \"date:{property}:start\", \"date:{property}:end\" (optional), and\n\t \"date:{property}:is_datetime\" (0 or 1)\n\t- Place properties: Split into \"place:{property}:name\", \"place:{property}:address\",\n\t \"place:{property}:latitude\", \"place:{property}:longitude\", and\n\t \"place:{property}:google_place_id\" (optional)\n\t- Number properties: Use JavaScript numbers (not strings)\n\t- Checkbox properties: Use \"__YES__\" for checked, \"__NO__\" for unchecked\n\t- Relation properties: Use an array of related page URLs or page IDs, e.g.\n\t [\"https://www.notion.so/26ab1f9f4c5f80b18d3bd10a6b1d2f4e\", \"26ab1f9f-4c5f-80b1-8d3b-d10a6b1d2f4e\"]\n\t- Files properties: Use a JSON array of file IDs, Notion Folder URLs, and/or tags\n\t copied from fetch output. Folders are stored as native Folder references, not ordinary links.\n\n\t**Special property naming**: Properties named \"id\" or \"url\" (case insensitive) must be\n\tprefixed with \"userDefined:\" (e.g., \"userDefined:URL\", \"userDefined:id\")\n\n\t\tFor pages outside of a database:\n\t\t- The only allowed property is \"title\",\twhich is the title of the page in inline markdown format.\n\n\t\t## Content\n\n\t\tNotion page content is a string in Notion-flavored Markdown format.\n\n\t\t**IMPORTANT**: For the complete Markdown specification, first\n\t\tread the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool.\n\t\tDo NOT guess or hallucinate Markdown syntax.\n\n\t\tFor small edits, send the smallest edit region that captures the intended change. Prefer\n\t\t\"update_content\" for targeted search-and-replace edits, or \"insert_content\" when you only\n\t\tneed to prepend or append content. Avoid full-page \"replace_content\" when \"update_content\"\n\t\tor \"insert_content\" is sufficient, because resubmitting unchanged page content makes the\n\t\toperation slower and more likely to hit async processing limits.\n\n\t\tUse \"insert_content\" to add content at the beginning or end of a page. If position is omitted,\n\t\tthe content is appended to the end of the page.\n\n\t\tBefore using \"update_content\", use the \"fetch\" tool first to get the existing content and find\n\t\tthe Markdown snippets to use in the \"update_content\" command's old_str fields.\n\n\t\t### Preserving Child Pages and Databases\n\n\t\tWhen using \"replace_content\", the operation will check if any\n\t\tchild pages or databases would be deleted. If so, it will fail with an error listing the\n\t\taffected items.\n\n\t\tTo preserve child pages/databases, include them in new_str using `` or\n\t\t`` tags. Get the exact URLs from the \"fetch\" tool output.\n\n\t\t**CRITICAL**: To intentionally delete child content:\n\t\tif the call failed with validation and requires `allow_deleting_content` to be true,\n\t\tDO NOT automatically assume the content should be deleted.\n\t\tALWAYS show the list of pages to be deleted and ask for user confirmation before proceeding.\n\n\t\t## Icon and Cover\n\n\t\tYou can set or remove a page's icon and cover alongside any command.\n\t\t- \"icon\": An emoji character (e.g. \"🚀\"), a custom emoji by name (e.g. \":rocket_ship:\"),\n\t\t or an external image URL. Use \"none\" to remove. Omit to leave unchanged.\n\t\t- \"cover\": An external image URL. Use \"none\" to remove. Omit to leave unchanged.\n\n\t\t## AI skills\n\n\t\tSet `is_skill` to `true` to mark the page as an AI skill, or `false` to remove the\n\t\tAI skill designation. This can be set alongside any command. To change only the skill\n\t\tstatus without making another page change, use the\n\t\t`update_properties` command and omit `properties`.\n\n\t\t## Examples\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_properties\",\n\t\t\t\"properties\": {\"title\": \"My Page\"},\n\t\t\t\"icon\": \"🚀\",\n\t\t\t\"cover\": \"https://example.com/cover.jpg\"\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_properties\",\n\t\t\t\"properties\": {\n\t\t\t\t\"title\": \"New Page Title\",\n\t\t\t\t\"status\": \"In Progress\",\n\t\t\t\t\"priority\": 5,\n\t\t\t\t\"checkbox\": \"__YES__\",\n\t\t\t\t\"related_tasks\": [\"26ab1f9f-4c5f-80b1-8d3b-d10a6b1d2f4e\"],\n\t\t\t\t\"date:deadline:start\": \"2024-12-25\",\n\t\t\t\t\"date:deadline:is_datetime\": 0,\n\t\t\t\t\"place:office:name\": \"HQ\",\n\t\t\t\t\"place:office:latitude\": 37.7749,\n\t\t\t\t\"place:office:longitude\": -122.4194\n\t\t\t}\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"replace_content\",\n\t\t\t\"new_str\": \"# New Section\\nUpdated content goes here\"\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_content\",\n\t\t\t\"content_updates\": [\n\t\t\t\t{\n\t\t\t\t\t\"old_str\": \"# Old Section\\nOld content here\",\n\t\t\t\t\t\"new_str\": \"# New Section\\nUpdated content goes here\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"insert_content\",\n\t\t\t\"content\": \"## Latest update\\n\\nStatus update goes here\",\n\t\t\t\"position\": { \"type\": \"start\" }\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_content\",\n\t\t\t\"content_updates\": [\n\t\t\t\t{\n\t\t\t\t\t\"old_str\": \"## Previous section\\nExisting content\",\n\t\t\t\t\t\"new_str\": \"## Previous section\\nExisting content\\n\\n## New Section\\nContent to insert goes here\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_content\",\n\t\t\t\"content_updates\": [\n\t\t\t\t{\n\t\t\t\t\t\"old_str\": \"Old text 1\",\n\t\t\t\t\t\"new_str\": \"New text 1\"\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"old_str\": \"Old text 2\",\n\t\t\t\t\t\"new_str\": \"New text 2\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t## Templates\n\n\t\tYou can apply a template to an existing page using the \"apply_template\" command.\n\t\tThe template content is appended to the page asynchronously. Get template IDs from\n\t\tthe section in the fetch tool results for a database, or use any page ID\n\t\tas a template.\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"apply_template\",\n\t\t\t\"template_id\": \"a5da15f6-b853-455d-8827-f906fb52db2b\"\n\t\t}\n\t\t\n\n\t\t## Verification\n\n\t\tYou can verify or unverify a page using the \"update_verification\" command.\n\t\tVerification marks a page as reviewed and up-to-date. Requires a Business or Enterprise\n\t\tplan (or the page must be in a wiki).\n\n\t\tWhen updating verification, the owner will be automatically set to the authenticated actor.\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_verification\",\n\t\t\t\"verification_status\": \"verified\",\n\t\t\t\"verification_expiry_days\": 90\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_verification\",\n\t\t\t\"verification_status\": \"verified\"\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_verification\",\n\t\t\t\"verification_status\": \"unverified\"\n\t\t}\n\t\t" } }, "required": ["type", "update_page"], "title": "Update Page" }, { "type": "object", "properties": { "type": { "type": "string", "const": "convert_page_to_skill", "description": "The name of the tool to run." }, "convert_page_to_skill": { "type": "object", "properties": { "page_url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri", "description": "The full Notion URL of the page to mark as an AI skill." } }, "required": ["page_url"], "description": "The parameters for the convert_page_to_skill tool. Mark a Notion page as an AI skill. The page must be in the current workspace, and the authenticated user must have permission to edit it. Use this tool only when the user wants the page to become a skill." } }, "required": ["type", "convert_page_to_skill"], "title": "Convert Page To Skill" }, { "type": "object", "properties": { "type": { "type": "string", "const": "move_pages", "description": "The name of the tool to run." }, "move_pages": { "type": "object", "properties": { "page_or_database_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "description": "An array of up to 100 page or database IDs to move. IDs are v4 UUIDs and can be supplied with or without dashes (e.g. extracted from a or URL given by the \"search\" or \"fetch\" tool). Data Sources under Databases can't be moved individually." }, "new_parent": { "oneOf": [ { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the parent page (with or without dashes), for example, 195de9221179449fab8075a27c979105" }, "type": { "type": "string", "const": "page_id", "description": "Always `page_id`" } }, "required": ["page_id"] }, { "type": "object", "properties": { "database_id": { "type": "string", "description": "The ID of the parent database (with or without dashes), for example, 195de9221179449fab8075a27c979105" }, "type": { "type": "string", "const": "database_id", "description": "Always `database_id`" } }, "required": ["database_id"] }, { "type": "object", "properties": { "data_source_id": { "type": "string", "description": "The ID of the parent data source (collection), with or without dashes. For example, f336d0bc-b841-465b-8045-024475c079dd" }, "type": { "type": "string", "const": "data_source_id", "description": "Always `data_source_id`" } }, "required": ["data_source_id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "workspace", "description": "The parent type." } }, "required": ["type"] } ], "description": "The new parent under which the pages will be moved. This can be a page, the workspace, a database, or a specific data source under a database when there are multiple. Moving pages to the workspace level adds them as private pages and should rarely be used." } }, "required": ["page_or_database_ids", "new_parent"], "description": "The parameters for the move_pages tool. Move one or more Notion pages or databases to a new parent." } }, "required": ["type", "move_pages"], "title": "Move Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "duplicate_page", "description": "The name of the tool to run." }, "duplicate_page": { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page to duplicate. This is a v4 UUID, with or without dashes, and can be parsed from a Notion page URL." } }, "required": ["page_id"], "description": "The parameters for the duplicate_page tool. Duplicate a Notion page. The page must be within the current workspace, and you must have permission to access it. The duplication completes asynchronously, so do not rely on the new page identified by the returned ID or URL to be populated immediately. Let the user know that the duplication is in progress and that they can check back later using the 'fetch' tool or by clicking the returned URL and viewing it in the Notion app." } }, "required": ["type", "duplicate_page"], "title": "Duplicate Page" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_database", "description": "The name of the tool to run." }, "create_database": { "allOf": [ { "type": "object", "properties": { "parent": { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the parent page, with or without dashes." }, "type": { "type": "string", "const": "page_id", "description": "Always `page_id`" } }, "required": ["page_id"], "description": "The parent under which to create the new database. If omitted, the database will be created as a private page at the workspace level." }, "title": { "type": "string", "description": "The title of the new database." }, "description": { "type": "string", "description": "The description of the new database." } } }, { "oneOf": [ { "type": "object", "properties": { "schema": { "type": "string", "description": "SQL DDL CREATE TABLE statement defining the database schema. Cannot be combined with database_type. Column names must be double-quoted and type options use single quotes." } }, "required": ["schema"] }, { "type": "object", "properties": { "database_type": { "type": "string", "enum": ["tasks", "projects", "skills"], "description": "Create a typed database with Notion's canonical required properties and metadata. Supported types: tasks, projects, skills." } }, "required": ["database_type"] } ] } ], "description": "The parameters for the create_database tool. Creates a new Notion database using SQL DDL syntax, or a typed database using\nNotion's canonical schema for tasks, projects, or skills.\n\nProvide exactly one of:\n- schema: a CREATE TABLE statement. If no title property is provided, \"Name\" is auto-added.\n- database_type: one of tasks, projects, or skills. The database is created with\n the canonical required properties and typed metadata used by Notion.\n\nReturns Markdown with schema, SQLite definition, and data source ID in\n tag for use with update_data_source and query_data_sources tools.\n\nType syntax:\n- Simple: TITLE, RICH_TEXT, DATE, PEOPLE, CHECKBOX, URL, EMAIL, PHONE_NUMBER, STATUS, FILES\n- SELECT('opt':color, ...) / MULTI_SELECT('opt':color, ...)\n- NUMBER [FORMAT 'dollar'] / FORMULA('expression')\n- RELATION('data_source_id') — one-way relation\n- RELATION('data_source_id', DUAL) — two-way relation\n- RELATION('data_source_id', DUAL 'synced_name') — two-way with synced property name\n- RELATION('data_source_id', DUAL 'synced_name' 'synced_id') — two-way with synced name and ID (for self-relations)\n- ROLLUP('rel_prop', 'target_prop', 'function')\n- UNIQUE_ID [PREFIX 'X'] / CREATED_TIME / LAST_EDITED_TIME\n- Any column: COMMENT 'description text'\nColors: default, gray, brown, orange, yellow, green, blue, purple, pink, red\n\n{\"schema\": \"CREATE TABLE (\\\"Name\\\" TITLE)\"}\n{\"database_type\": \"tasks\", \"title\": \"Tasks\"}\n{\"parent\": {\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\"}, \"title\": \"Projects\", \"schema\": \"CREATE TABLE (\\\"Name\\\" TITLE, \\\"Budget\\\" NUMBER FORMAT 'dollar', \\\"Tags\\\" MULTI_SELECT('eng':blue, 'design':pink), \\\"Task ID\\\" UNIQUE_ID PREFIX 'PRJ')\"}\n{\"title\": \"Tasks\", \"schema\": \"CREATE TABLE (\\\"Name\\\" TITLE, \\\"Parent\\\" RELATION('ds_id', DUAL 'Children' 'children'), \\\"Children\\\" RELATION('ds_id', DUAL 'Parent' 'parent'))\"}" } }, "required": ["type", "create_database"], "title": "Create Database" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_folder", "description": "The name of the tool to run." }, "create_folder": { "type": "object", "properties": { "parent": { "oneOf": [ { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page that will own the Folder." } }, "additionalProperties": false, "required": ["page_id"] }, { "type": "object", "properties": { "folder_id": { "type": "string", "description": "The ID of the Folder that will contain the new Folder." } }, "additionalProperties": false, "required": ["folder_id"] } ], "description": "Where to create the Folder." }, "title": { "type": "string", "description": "The title of the new Folder." } }, "required": ["parent", "title"], "description": "The parameters for the create_folder tool. Creates an empty Notion Folder. Set parent.page_id for a top-level Folder owned\nby a page, or parent.folder_id to create a nested Folder inside another Folder.\nA page-owned Folder is not inserted into the page's content. A nested Folder is\nappended to its parent Folder's content. The Folder inherits access from its\nparent.\n\nThis tool creates only the empty Folder. It is non-idempotent and creates a new\nFolder on every successful call." } }, "required": ["type", "create_folder"], "title": "Create Folder" }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_folder", "description": "The name of the tool to run." }, "update_folder": { "type": "object", "properties": { "folder_id": { "type": "string", "description": "The ID of the Folder to update." }, "command": { "type": "string", "enum": [ "add_files", "remove_files", "add_subfolder" ], "description": "The Folder update to apply." }, "file_upload_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "uniqueItems": true, "description": "Required for add_files. One or more file upload IDs returned by the file upload tools." }, "file_urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "uniqueItems": true, "description": "Required for remove_files. The exact file URLs shown in the Folder's latest fetch output." }, "title": { "type": "string", "description": "Required for add_subfolder. The new Folder's title." } }, "additionalProperties": false, "required": ["folder_id", "command"], "description": "The parameters for the update_folder tool. Update an existing Notion Folder with an explicit Folder operation.\n\n- Use add_files with file upload IDs returned by the upload tools.\n- Fetch the Folder first, then use remove_files with the exact file URLs from\n that fetch result.\n- Use add_subfolder to create and insert a new nested Folder.\n\nUse exactly one command shape; do not mix their arguments:\n- {\"command\":\"add_files\",\"file_upload_ids\":[\"...\"]}\n- {\"command\":\"remove_files\",\"file_urls\":[\"...\"]}\n- {\"command\":\"add_subfolder\",\"title\":\"...\"}\n\nThe Folder ID may be provided with or without dashes." } }, "required": ["type", "update_folder"], "title": "Update Folder" }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_data_source", "description": "The name of the tool to run." }, "update_data_source": { "type": "object", "properties": { "data_source_id": { "type": "string", "description": "The data source to update. Accepts a collection:// URI from tags, a bare UUID, or a database ID (only if the database has a single data source)." }, "statements": { "type": "string", "description": "Semicolon-separated SQL DDL statements to update the schema. Supports ADD COLUMN, DROP COLUMN, RENAME COLUMN, ALTER COLUMN SET." }, "title": { "type": "string", "description": "The new title of the data source." }, "description": { "type": "string", "description": "The new description of the data source." }, "is_inline": { "type": "boolean", "description": "Whether the database should display inline (true) or as full page (false). Only applicable for single-source databases." }, "in_trash": { "type": "boolean", "description": "Move data source to trash. Cannot be undone without Notion UI." } }, "required": ["data_source_id"], "description": "The parameters for the update_data_source tool. Update a Notion data source's schema, title, or attributes using SQL DDL statements.\nReturns Markdown showing updated structure and schema.\n\nAccepts a data source ID (collection ID from fetch response's tag)\nor a single-source database ID. Multi-source databases require the specific\ndata source ID.\n\nThe statements param accepts semicolon-separated DDL statements:\n- ADD COLUMN \"Name\" - add a new property\n- DROP COLUMN \"Name\" - remove a property\n- RENAME COLUMN \"Old\" TO \"New\" - rename a property\n- ALTER COLUMN \"Name\" SET - change type/options\n\nSame type syntax as create_database. Key types:\n- SELECT('opt':color, ...) / MULTI_SELECT('opt':color, ...)\n- NUMBER [FORMAT 'dollar'] / FORMULA('expression')\n- RELATION('ds_id') / RELATION('ds_id', DUAL) / RELATION('ds_id', DUAL 'synced_name' 'synced_id')\n- ROLLUP('rel_prop', 'target_prop', 'function') / UNIQUE_ID [PREFIX 'X']\n- Simple: TITLE, RICH_TEXT, DATE, PEOPLE, CHECKBOX, URL, EMAIL, PHONE_NUMBER, STATUS, FILES\n\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"statements\": \"ADD COLUMN \\\"Priority\\\" SELECT('High':red, 'Medium':yellow, 'Low':green); ADD COLUMN \\\"Due Date\\\" DATE\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"statements\": \"RENAME COLUMN \\\"Status\\\" TO \\\"Project Status\\\"\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"statements\": \"DROP COLUMN \\\"Old Property\\\"\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"statements\": \"ADD COLUMN \\\"Parent\\\" RELATION('f336d0bc-b841-465b-8045-024475c079dd', DUAL 'Children' 'children'); ADD COLUMN \\\"Children\\\" RELATION('f336d0bc-b841-465b-8045-024475c079dd', DUAL 'Parent' 'parent')\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"title\": \"Project Tracker 2024\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"in_trash\": true}\n\nNotes: Cannot delete/create title properties. Max one unique_id property.\nCannot update synced databases. Use \"fetch\" first to see current schema\nand get the data source ID from tags." } }, "required": ["type", "update_data_source"], "title": "Update Data Source" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_comment", "description": "The name of the tool to run." }, "create_comment": { "allOf": [ { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page to comment on (with or without dashes)." }, "discussion_id": { "type": "string", "description": "The ID or URL of an existing discussion to reply to (e.g., discussion://pageId/blockId/discussionId)." }, "selection_with_ellipsis": { "type": "string", "description": "Unique start and end snippet of the content to comment on.\nDO NOT provide the entire string. Instead, provide up to the first ~10 characters, an ellipsis, and then up to the last ~10 characters.\nMake sure you provide enough of the start and end snippet to uniquely identify the content.\nFor example: \"# Section heading...last paragraph.\"" } }, "required": ["page_id"] }, { "oneOf": [ { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemRequest" }, "maxItems": 100, "description": "An array of rich text objects that represent the content of the comment. Provide exactly one of rich_text or markdown." } }, "required": ["rich_text"] }, { "type": "object", "properties": { "markdown": { "type": "string", "description": "The content of the comment as a Markdown string. Provide exactly one of markdown or rich_text. For exact syntax, read the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool. Use only the Rich text types and Mentions syntax that comments support. Comments support inline formatting (bold, italic, strikethrough, underline, code, links), inline math using $`Equation`$, and user/page/database/date mention tags such as . To attach a file created by create-file-upload or create-attachment, include its returned suggested_markdown on a separate line; up to three file attachments are supported. Do not use UI shortcuts like @today, @name, [[page]], or autocomplete-style emoji syntax; those are editor affordances, not markdown syntax. Mention tags must include a real url where required by the spec. Other block-level Markdown such as fenced code blocks, headings, lists, tables, and blockquotes is stored as plain comment text rather than rendered as blocks." } }, "required": ["markdown"] } ] } ], "description": "The parameters for the create_comment tool. Add a comment to a page or specific content.\n\nCreates a new comment. Provide `page_id` to identify the page, then choose ONE targeting mode:\n- `page_id` alone: Page-level comment on the entire page\n- `page_id` + `selection_with_ellipsis`: Comment on specific block content\n- `discussion_id`: Reply to an existing discussion thread (page_id is still required)\n\nProvide exactly one content format:\n- `markdown`: Preferred. Inline Notion-flavored Markdown for comment text. For exact syntax, read the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool. Use only the Rich text types and Mentions syntax that comments support. Comments support inline formatting (bold, italic, strikethrough, underline, code, links), inline math using `$`Equation`$`, and user/page/database/date mention tags such as ``. To attach a file created by `create-file-upload` or `create-attachment`, include its returned `suggested_markdown` on a separate line; up to three file attachments are supported. Do not use UI shortcuts like `@today`, `@name`, `[[page]]`, or autocomplete-style emoji syntax; those are editor affordances, not markdown syntax. Mention tags must include a real `url` where required by the spec. Other block-level Markdown such as headings, lists, tables, blockquotes, and fenced code blocks is stored as plain comment text rather than rendered as blocks.\n- `rich_text`: Array of rich text objects.\n\nFor content targeting, use `selection_with_ellipsis` with ~10 chars from start and end: \"# Section Ti...tle content\"\n\n\n{\"page_id\": \"uuid\", \"markdown\": \"Comment with **important** context.\"}\n\n\n{\"page_id\": \"uuid\", \"selection_with_ellipsis\": \"# Meeting No...es heading\",\n \"markdown\": \"Comment on this section.\"}\n\n\n{\"page_id\": \"uuid\", \"discussion_id\": \"discussion://pageId/blockId/discussionId\",\n \"markdown\": \"Reply with [context](https://example.com).\"}\n" } }, "required": ["type", "create_comment"], "title": "Create Comment" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_comments", "description": "The name of the tool to run." }, "get_comments": { "type": "object", "properties": { "page_id": { "type": "string", "description": "Identifier for a Notion page." }, "include_resolved": { "type": "boolean", "description": "Include resolved discussions in the response. Defaults to false." }, "include_all_blocks": { "type": "boolean", "description": "Include discussions on child blocks, not just page-level discussions. Defaults to false." }, "discussion_id": { "type": "string", "description": "Fetch a specific discussion by ID or discussion URL (e.g., discussion://pageId/blockId/discussionId)." } }, "required": ["page_id"], "description": "The parameters for the get_comments tool. Get comments and discussions from a Notion page.\n\nReturns discussions with full comment content in XML format.\nBy default, returns page-level discussions only.\n\nTip: Use the `fetch` tool with `include_discussions: true` first to see where discussions\nare anchored in the page content, then use this tool to retrieve full discussion threads.\nThe `discussion://` URLs in the fetch output match the discussion IDs returned here.\n\nParameters:\n- `include_all_blocks`: Include discussions on child blocks (default: false)\n- `include_resolved`: Include resolved discussions (default: false)\n- `discussion_id`: Fetch a specific discussion by ID or URL\n\n{\"page_id\": \"page-uuid\"}\n{\"page_id\": \"page-uuid\", \"include_all_blocks\": true}\n{\"page_id\": \"page-uuid\", \"discussion_id\": \"discussion://pageId/blockId/discussionId\"}" } }, "required": ["type", "get_comments"], "title": "Get Comments" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_async_task", "description": "The name of the tool to run." }, "get_async_task": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1, "examples": ["task_abc123"], "description": "The ID of the async task to retrieve, as returned in the async_task response of the tool that started it." } }, "required": ["task_id"], "description": "The parameters for the get_async_task tool. Retrieves the current status of an async task that was started by another tool\n(for example, \"create_pages\" called with \"allow_async\": true).\n\nThe status is one of \"queued\", \"running\", \"retrying\", \"succeeded\", or \"failed\".\nWhen the task has succeeded, the operation's result is included; when it has\nfailed, an error is included instead.\n\nPoll this tool with the \"task_id\" from the original tool's \"async_task\" response.\nWait briefly between polls — the original response includes a suggested backoff.\n\n\n1. Check a task's status: {\"task_id\": \"task_abc123\"}\n" } }, "required": ["type", "get_async_task"], "title": "Get Async Task" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_teams", "description": "The name of the tool to run." }, "get_teams": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional search query to filter teams by name (case-insensitive)." } }, "description": "The parameters for the get_teams tool. Retrieves a list of teams (teamspaces) in the current workspace. Shows which teams\nexist, user membership status, IDs, names, and roles.\n\nTeams are returned split by membership status and limited to a maximum of\n10 results.\n\n\n1. List all teams (up to the limit of each type): {}\n\n2. Search for teams by name: {\"query\": \"engineering\"}\n\n3. Find a specific team: {\"query\": \"Product Design\"}\n" } }, "required": ["type", "get_teams"], "title": "Get Teams" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_users", "description": "The name of the tool to run." }, "get_users": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional search query to filter users by name or email (case-insensitive)." }, "start_cursor": { "type": "string", "minLength": 1, "description": "Cursor for pagination. Use the next_cursor value from the previous response to get the next page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of users to return per page (default: 100, max: 100)." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Return only the user matching this ID. Pass \"self\" to fetch the current user." } }, "description": "The parameters for the get_users tool. Retrieves a list of users in the current workspace. Shows workspace members\nand guests with their IDs, names, emails (if available), and types (person or bot).\n\nSupports cursor-based pagination to iterate through all users in the workspace.\n\n\n1. List all users (first page): {}\n\n2. Search for users by name or email: {\"query\": \"john\"}\n\n3. Get next page of results: {\"start_cursor\": \"abc123\"}\n\n4. Set custom page size: {\"page_size\": 20}\n\n5. Fetch a specific user by ID: {\"user_id\": \"00000000-0000-4000-8000-000000000000\"}\n\n6. Fetch the current user: {\"user_id\": \"self\"}\n" } }, "required": ["type", "get_users"], "title": "Get Users" }, { "type": "object", "properties": { "type": { "type": "string", "const": "reply_to_slack_thread", "description": "The name of the tool to run." }, "reply_to_slack_thread": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The Slack message to post as a reply in the triggering thread. Use Slack markdown formatting." }, "unfurl_links": { "type": "boolean", "description": "Whether Slack should unfurl links in the reply. Defaults to true." } }, "required": ["message"], "description": "The parameters for the reply_to_slack_thread tool. Reply to the Slack thread that triggered the current workflow run.\n\nThis tool is only available to external agent harnesses running from a Slack-triggered\nworkflow with an active Slack connection. It cannot reply to arbitrary Slack channels\nor threads; the destination is fixed to the triggering thread for this workflow run.\nUse Slack markdown formatting in message text." } }, "required": ["type", "reply_to_slack_thread"], "title": "Reply To Slack Thread" }, { "type": "object", "properties": { "type": { "type": "string", "const": "answer_question", "description": "The name of the tool to run." }, "answer_question": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Question to answer using content from the user's Notion workspace." } }, "required": ["question"], "description": "The parameters for the answer_question tool. Get a single AI-generated answer to a question using content from the user's\nNotion workspace. This tool does not search connected sources such as Slack,\nGoogle Drive, or GitHub. Returns one concise answer, not a list of results.\n\nUse this when you want a direct answer and don't need to read the underlying\npages yourself. It's faster and far cheaper on tokens than fetching many search\nresults and synthesizing them yourself.\n\nUse search instead if you want a ranked list of results to read, filter, or fetch\nin full, or if you need precise control over which sources inform the answer. If\nan answer isn't enough for the task, fall back to search to retrieve and read the\nfull results.\n\nFree during beta." } }, "required": ["type", "answer_question"], "title": "Answer Question" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_data_sources", "description": "The name of the tool to run." }, "query_data_sources": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "data_source_urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Notion data source URLs whose SQLite tables are available to the query;\neach data source is exposed as a table named by its URL. Obtain them from the\nfetch tool, in the format: collection://f336d0bc-b841-465b-8045-024475c079dd" }, "query": { "type": "string", "description": "Read-only SQLite query to execute against the data sources. Use a data\nsource URL as the table name, e.g. SELECT * FROM \"collection://...\" WHERE ....\nInclude every needed filter in WHERE (filters on views of the data source are\nnot automatically applied). For time comparisons or ordering, normalize text\ntimestamps with datetime(...) or date(...)." }, "mode": { "type": "string", "const": "sql", "description": "Optional mode parameter. Defaults to 'sql' if not specified." }, "params": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "maxItems": 100, "description": "Positional parameters bound to `?` placeholders in the query. Prefer\nparameterized queries over string interpolation. Use \"__YES__\" for checked\ncheckboxes and \"__NO__\" for unchecked checkboxes." } }, "additionalProperties": false, "required": ["data_source_urls", "query"], "title": "Sql" }, { "type": "object", "properties": { "mode": { "type": "string", "const": "view", "description": "Mode for executing a database view's existing query" }, "view_url": { "type": "string", "description": "URL of a specific database view to query.\nExample: https://www.notion.so/workspace/db-id?v=view-id" }, "start_cursor": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Cursor for pagination. Use the next_cursor value from the previous response to get the next page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of rows to return per page (default: 100, max: 100)." }, "is_archived": { "type": "boolean", "description": "Optional archive selector. Omitted or false queries non-archived rows only; true queries archived rows only." } }, "additionalProperties": false, "required": ["mode", "view_url"], "title": "View" } ], "description": "The data required for querying data sources" } }, "required": ["data"], "description": "The parameters for the query_data_sources tool. Query data from Notion databases using SQL or by specifying a view. This is the canonical replacement for the deprecated query_database_view tool.\n\nBy default, uses SQL mode to execute SQLite queries against one or more data sources.\nAlternatively, use view mode to execute a database view's existing filters and sorts. Pass the same view_url previously used with query_database_view.\nArchive selection is supported in view mode only. SQL mode does not accept\n\"is_archived\"; SQL archive support is a separate infrastructure follow-up.\n\nLimits: View mode is available without a tool-specific quota on every plan.\nSQL is unlimited on Business and Enterprise plans with Notion AI. Other plans\nhave a shared workspace usage limit for single-data-source queries and cannot\nquery multiple data sources at once.\n\nPrerequisites:\n1. Use the \"fetch\" tool first to get database schema and data source URLs\n2. Data source URLs are found in tags in fetch results\n\nSQL mode (default):\nExecute custom SQLite queries against one or more data sources.\n- Use data source URLs as table names in your query\n- Supports parameterized queries for security\n- Checkbox values: use \"__YES__\" for checked, \"__NO__\" for unchecked\n\nExamples:\n1. Simple query without explicit mode (defaults to SQL):\n{\n \"data\": {\n \"data_source_urls\": [\"collection://f336d0bc-b841-465b-8045-024475c079dd\"],\n \"query\": \"SELECT * FROM \\\"collection://f336d0bc-b841-465b-8045-024475c079dd\\\" LIMIT 10\"\n }\n}\n\n2. Query with parameters:\n{\n \"data\": {\n \"mode\": \"sql\",\n \"data_source_urls\": [\"collection://abc123\"],\n \"query\": \"SELECT * FROM \\\"collection://abc123\\\" WHERE Status = ? AND Priority = ?\",\n \"params\": [\"In Progress\", \"High\"]\n }\n}\n\n3. Query checkboxes:\n{\n \"data\": {\n \"data_source_urls\": [\"collection://def456\"],\n \"query\": \"SELECT * FROM \\\"collection://def456\\\" WHERE Completed = ?\",\n \"params\": [\"__YES__\"]\n }\n}\n\nView mode:\nExecute a specific database view's query with its filters and sorts.\nOmit \"is_archived\" or set it to false for non-archived rows. Set\n\"is_archived\": true to apply the view inside the archived partition.\nWhen the response has \"has_more\": true, pass its \"next_cursor\" as\n\"start_cursor\" in a follow-up view-mode request with the same \"is_archived\"\nvalue.\n\nExample:\n{\n \"data\": {\n \"mode\": \"view\",\n \"view_url\": \"https://www.notion.so/workspace/Tasks-DB-abc123?v=def456\",\n \"is_archived\": false\n }\n}\n\nCommon use cases:\n- Aggregate data across databases\n- Filter records by complex conditions\n- Export data for analysis\n- Validate data quality\n- Generate reports from database content" } }, "required": ["type", "query_data_sources"], "title": "Query Data Sources" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_multiple_data_sources", "description": "The name of the tool to run." }, "query_multiple_data_sources": { "type": "object", "properties": { "query": { "type": "string", "description": "Read-only SQLite query to execute against the data sources. Use a data\nsource URL as the table name, e.g. SELECT * FROM \"collection://...\" WHERE ....\nInclude every needed filter in WHERE (filters on views of the data source are\nnot automatically applied). For time comparisons or ordering, normalize text\ntimestamps with datetime(...) or date(...)." }, "data_source_urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 2, "description": "Notion data source URLs whose SQLite tables are available to the query;\neach data source is exposed as a table named by its URL. Obtain them from the\nfetch tool, in the format: collection://f336d0bc-b841-465b-8045-024475c079dd" }, "params": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "maxItems": 100, "description": "Positional parameters bound to `?` placeholders in the query. Prefer\nparameterized queries over string interpolation. Use \"__YES__\" for checked\ncheckboxes and \"__NO__\" for unchecked checkboxes." }, "mode": { "type": "string", "const": "sql", "description": "Optional SQL mode marker. This tool only supports SQL queries." } }, "additionalProperties": false, "required": ["query", "data_source_urls"], "description": "The parameters for the query_multiple_data_sources tool. Query data across multiple Notion data sources using read-only SQLite SQL.\n\nUse this tool for JOINs, UNIONs, comparisons, and aggregations that need two or more data sources. Queries across multiple data sources require a Business or Enterprise plan with Notion AI. Use query_data_sources instead when you need one data source or a saved database view.\n\nPrerequisites:\n1. Use the \"fetch\" tool first to get each data source's schema and collection:// URL.\n2. Data source URLs are found in tags in fetch results.\n\nSQL:\n- Use each collection:// URL as a quoted SQLite table name in the query.\n- Bind untrusted values with ? placeholders and params; do not interpolate them into SQL.\n- Include every needed filter in WHERE. Saved-view filters and sorts are not automatically applied.\n- Checkbox values: use \"__YES__\" for checked and \"__NO__\" for unchecked.\n\nReturns matching rows, the queried data source IDs, and whether results were truncated." } }, "required": ["type", "query_multiple_data_sources"], "title": "Query Multiple Data Sources" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_database_view", "description": "The name of the tool to run." }, "query_database_view": { "type": "object", "properties": { "view_url": { "type": "string", "description": "URL of a specific database view to query.\nExample: https://www.notion.so/workspace/db-id?v=view-id" }, "start_cursor": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Cursor for pagination. Use the next_cursor value from the previous response to get the next page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of rows to return per page (default: 100, max: 100)." }, "is_archived": { "type": "boolean", "description": "Optional archive selector. Omitted or false queries non-archived rows only; true queries archived rows only." } }, "required": ["view_url"], "description": "The parameters for the query_database_view tool. [DEPRECATED] Use query_data_sources with mode: \"view\" and the same view_url instead. This tool will be removed in a future release.\n\nQuery data from a Notion database view.\n\nExecutes a database view's existing filters, sorts, and column selections to return matching pages.\nUse this to query a view exactly as configured. For custom SQL queries, aggregation, or querying across multiple data sources, use query_data_sources instead.\nBy default, it returns non-archived rows only. Set \"is_archived\": true to query archived rows only.\n\nPrerequisites:\n1. Use the \"fetch\" tool first to get the database and its view URLs\n2. View URLs are found in database responses, typically in the format:\n https://www.notion.so/workspace/db-id?v=view-id\n\nExample:\n{\n \"view_url\": \"https://www.notion.so/workspace/Tasks-DB-abc123?v=def456\",\n \"is_archived\": false\n}\n\nWhen the response has \"has_more\": true, pass its \"next_cursor\" as\n\"start_cursor\" in a follow-up request with the same \"is_archived\" value.\n\nCommon use cases:\n- Query databases using pre-defined views (filters/sorts already configured), e.g. look for all tickets marked \"In Progress\" in a Tasks DB\n- Export filtered data for analysis\n- Generate reports from database content" } }, "required": ["type", "query_database_view"], "title": "Query Database View" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_meeting_notes", "description": "The name of the tool to run." }, "query_meeting_notes": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "operator": { "type": "string", "enum": ["and", "or"], "description": "Operator for combinator filters." }, "filters": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "enum": [ "title", "attendees", "created_time", "created_by", "last_edited_time", "last_edited_by", "notion://meeting_notes/attendees" ], "description": "Which meeting-note property to filter on. Prefer the short names; the schema URI form is accepted for compatibility." }, "filter": { "oneOf": [ { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "string_is", "string_is_not", "string_contains", "string_does_not_contain", "string_starts_with", "string_ends_with" ], "description": "How to compare the text." }, "value": { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "string", "description": "The literal text the operator compares against." } }, "additionalProperties": false, "required": ["type", "value"], "description": "The text to compare against." } }, "additionalProperties": false, "required": ["operator", "value"] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "person_contains", "person_does_not_contain" ], "description": "Whether the property must contain the people listed." }, "value": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "object", "properties": { "table": { "type": "string", "const": "notion_user", "description": "Always `notion_user`" }, "id": { "type": "string", "examples": [ "3f2b25f3-0a52-4a90-8f0d-5a3f0e6c1d2e", "user://3f2b25f3-0a52-4a90-8f0d-5a3f0e6c1d2e" ], "description": "The user's ID, as a UUID or the `user://` form returned by user search." } }, "additionalProperties": false, "required": [ "table", "id" ], "description": "Pointer to the Notion user to match." } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "me", "description": "Always `me`" } }, "additionalProperties": false, "required": [ "type", "value" ] } ] }, "maxItems": 100, "description": "The people to compare against." } }, "additionalProperties": false, "required": ["operator", "value"] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "date_is", "date_is_before", "date_is_after", "date_is_on_or_before", "date_is_on_or_after" ], "description": "How to compare the date." }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "enum": [ "today", "tomorrow", "yesterday", "one_week_ago", "one_week_from_now", "one_month_ago", "one_month_from_now" ], "description": "One of: `today`, `tomorrow`, `yesterday`, `one_week_ago`, `one_week_from_now`, `one_month_ago`, `one_month_from_now`" } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "The calendar date as an ISO 8601 date string." } }, "additionalProperties": false, "required": [ "type", "start_date" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "datetime", "description": "Always `datetime`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "The calendar date as an ISO 8601 date string." }, "start_time": { "type": "string", "examples": [ "09:30" ], "description": "The time of day in 24-hour HH:MM format." }, "time_zone": { "type": "string", "examples": [ "America/Los_Angeles" ], "description": "The IANA time zone name the time is interpreted in." } }, "additionalProperties": false, "required": [ "type", "start_date", "start_time", "time_zone" ] } ], "description": "Use the is_empty operator to match an unset date." } }, "additionalProperties": false, "required": [ "type", "value" ] } ], "description": "The date to compare against." }, "use_end": { "type": "boolean", "description": "Compare against the end of a date range rather than its start." } }, "additionalProperties": false, "required": ["operator", "value"] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "date_is_within", "date_is_relative_to" ], "description": "How to compare the date against the range." }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "custom", "description": "Always `custom`" }, "direction": { "type": "string", "enum": [ "past", "future" ], "description": "Whether the window runs backwards or forwards from now." }, "unit": { "type": "string", "enum": [ "year", "month", "week", "day" ], "description": "One of: `year`, `month`, `week`, `day`" }, "count": { "type": "integer", "minimum": 1, "description": "How many units wide the window is." } }, "additionalProperties": false, "required": [ "type", "value", "direction", "unit", "count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "surrounding", "description": "Always `surrounding`" }, "unit": { "type": "string", "enum": [ "year", "month", "week", "day" ], "description": "One of: `year`, `month`, `week`, `day`" } }, "additionalProperties": false, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "enum": [ "this_week", "the_past_week", "the_past_month", "the_past_year", "the_next_week", "the_next_month", "the_next_year" ], "description": "One of: `this_week`, `the_past_week`, `the_past_month`, `the_past_year`, `the_next_week`, `the_next_month`, `the_next_year`" } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "object", "properties": { "type": { "type": "string", "const": "daterange", "description": "Always `daterange`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "Inclusive start of the range as an ISO 8601 date string, if any." }, "end_date": { "type": "string", "examples": [ "1991-01-04" ], "format": "date", "description": "Inclusive end of the range as an ISO 8601 date string, if any." } }, "additionalProperties": false, "required": ["type"], "description": "Use the is_empty operator to match an unset date." } }, "additionalProperties": false, "required": [ "type", "value" ] } ], "description": "The range to compare against." }, "use_end": { "type": "boolean", "description": "Compare against the end of a date range rather than its start." } }, "additionalProperties": false, "required": ["operator", "value"] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Whether the property must be empty or set." } }, "additionalProperties": false, "required": ["operator"] } ], "description": "The comparison to apply. Use the arm matching the property's type." } }, "additionalProperties": false, "required": ["property", "filter"] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": ["and", "or"], "description": "Whether every child must match, or any of them." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string", "enum": [ "title", "attendees", "created_time", "created_by", "last_edited_time", "last_edited_by", "notion://meeting_notes/attendees" ], "description": "Which meeting-note property to filter on. Prefer the short names; the schema URI form is accepted for compatibility." }, "filter": { "oneOf": [ { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "string_is", "string_is_not", "string_contains", "string_does_not_contain", "string_starts_with", "string_ends_with" ], "description": "How to compare the text." }, "value": { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "string", "description": "The literal text the operator compares against." } }, "additionalProperties": false, "required": [ "type", "value" ], "description": "The text to compare against." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "person_contains", "person_does_not_contain" ], "description": "Whether the property must contain the people listed." }, "value": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "object", "properties": { "table": { "type": "string", "const": "notion_user", "description": "Always `notion_user`" }, "id": { "type": "string", "examples": [ "3f2b25f3-0a52-4a90-8f0d-5a3f0e6c1d2e", "user://3f2b25f3-0a52-4a90-8f0d-5a3f0e6c1d2e" ], "description": "The user's ID, as a UUID or the `user://` form returned by user search." } }, "additionalProperties": false, "required": [ "table", "id" ], "description": "Pointer to the Notion user to match." } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "me", "description": "Always `me`" } }, "additionalProperties": false, "required": [ "type", "value" ] } ] }, "maxItems": 100, "description": "The people to compare against." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "date_is", "date_is_before", "date_is_after", "date_is_on_or_before", "date_is_on_or_after" ], "description": "How to compare the date." }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "enum": [ "today", "tomorrow", "yesterday", "one_week_ago", "one_week_from_now", "one_month_ago", "one_month_from_now" ], "description": "One of: `today`, `tomorrow`, `yesterday`, `one_week_ago`, `one_week_from_now`, `one_month_ago`, `one_month_from_now`" } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "The calendar date as an ISO 8601 date string." } }, "additionalProperties": false, "required": [ "type", "start_date" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "datetime", "description": "Always `datetime`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "The calendar date as an ISO 8601 date string." }, "start_time": { "type": "string", "examples": [ "09:30" ], "description": "The time of day in 24-hour HH:MM format." }, "time_zone": { "type": "string", "examples": [ "America/Los_Angeles" ], "description": "The IANA time zone name the time is interpreted in." } }, "additionalProperties": false, "required": [ "type", "start_date", "start_time", "time_zone" ] } ], "description": "Use the is_empty operator to match an unset date." } }, "additionalProperties": false, "required": [ "type", "value" ] } ], "description": "The date to compare against." }, "use_end": { "type": "boolean", "description": "Compare against the end of a date range rather than its start." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "date_is_within", "date_is_relative_to" ], "description": "How to compare the date against the range." }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "custom", "description": "Always `custom`" }, "direction": { "type": "string", "enum": [ "past", "future" ], "description": "Whether the window runs backwards or forwards from now." }, "unit": { "type": "string", "enum": [ "year", "month", "week", "day" ], "description": "One of: `year`, `month`, `week`, `day`" }, "count": { "type": "integer", "minimum": 1, "description": "How many units wide the window is." } }, "additionalProperties": false, "required": [ "type", "value", "direction", "unit", "count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "surrounding", "description": "Always `surrounding`" }, "unit": { "type": "string", "enum": [ "year", "month", "week", "day" ], "description": "One of: `year`, `month`, `week`, `day`" } }, "additionalProperties": false, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "enum": [ "this_week", "the_past_week", "the_past_month", "the_past_year", "the_next_week", "the_next_month", "the_next_year" ], "description": "One of: `this_week`, `the_past_week`, `the_past_month`, `the_past_year`, `the_next_week`, `the_next_month`, `the_next_year`" } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "object", "properties": { "type": { "type": "string", "const": "daterange", "description": "Always `daterange`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "Inclusive start of the range as an ISO 8601 date string, if any." }, "end_date": { "type": "string", "examples": [ "1991-01-04" ], "format": "date", "description": "Inclusive end of the range as an ISO 8601 date string, if any." } }, "additionalProperties": false, "required": [ "type" ], "description": "Use the is_empty operator to match an unset date." } }, "additionalProperties": false, "required": [ "type", "value" ] } ], "description": "The range to compare against." }, "use_end": { "type": "boolean", "description": "Compare against the end of a date range rather than its start." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Whether the property must be empty or set." } }, "additionalProperties": false, "required": ["operator"] } ], "description": "The comparison to apply. Use the arm matching the property's type." } }, "additionalProperties": false, "required": ["property", "filter"] }, "maxItems": 100, "description": "The conditions in this group. A group with no conditions matches nothing, so send at least one." } }, "additionalProperties": false, "required": ["operator", "filters"] } ] }, "maxItems": 100, "description": "Nested filters; each may be a combinator (and/or) or property filter." } }, "required": ["operator"], "description": "Acceptable filter for querying current user's meeting notes data source." } }, "description": "The parameters for the query_meeting_notes tool. Query the current user's meeting notes data source.\n\nApplies a filter over meeting note properties. Title keyword searching is done via filter on property \"title\" (e.g. string_contains).\nTitle keyword matching is case-insensitive; capitalization does not matter.\nReturns up to 50 rows of matching meeting notes.\n\nPrerequisites:\n1. Use the \"search\" tool to find people IDs if you need to filter by attendees\n\nQuery building:\n- Ignore terms semantically related to meeting outputs (e.g. \"summaries\", \"notes\", \"todos\", \"action items\", \"deliverables\"). These signal the user wants outcomes from their meetings, not a title filter.\n- For example, \"what are my meeting todos?\" means filter meetings and find action items — do NOT add a title filter for \"todos\".\n- Only add a title filter when confident the user is targeting a specific meeting title (e.g. \"standup\", \"sprint planning\", \"1:1 with Alice\").\n- Generic date phrases like \"recent meetings\", \"latest meetings\", \"meetings this week\", or \"yesterday's meetings\" should be interpreted as date range filters — never as title filters.\n- If a filter returns no results, simplify to a single term. The system is lexical, so multi-word title filters may not match.\n- Unless a user explicitly asks about a meeting titled with another user's name, assume they're referring to attendees or creators. Only add a title filter with a person's name as a fallback if attendee filtering returns no results.\n\nDefault behavior:\n- This tool by default returns meeting notes where the current user is an attendee or creator. There is no need to add a filter for the current user.\n\nFilterable properties:\n- \"title\" (text) — meeting title\n- \"attendees\" (person) — meeting attendees\n- \"created_time\" (date) — when the meeting note was created\n- \"created_by\" (person) — who created the meeting note\n- \"last_edited_time\" (date) — when the meeting note was last edited\n- \"last_edited_by\" (person) — who last edited the meeting note\n\nCombinator filters use \"filters\" (not \"operands\"):\n{\n \"operator\": \"and\" | \"or\",\n \"filters\": [ ... ]\n}\n\nDate filtering (recommended default: date_is_within):\n- Prefer \"date_is_within\" for relative windows like \"past N days/weeks/months\".\n- Relative (common): { type: \"relative\", value: \"the_past_week\" | \"the_past_month\" | \"this_week\" }\n- Relative (custom): { type: \"relative\", value: \"custom\", direction: \"past\" | \"future\", unit: \"day\" | \"week\" | \"month\" | \"year\", count: }\n- Exact range: { type: \"exact\", value: { type: \"daterange\", start_date: \"YYYY-MM-DD\", end_date: \"YYYY-MM-DD\" } }\n- Single-date operators (\"date_is\", \"date_is_before\", \"date_is_after\", \"date_is_on_or_before\", \"date_is_on_or_after\"):\n - Exact: { type: \"exact\", value: { type: \"date\", start_date: \"YYYY-MM-DD\" } }\n - Relative shortcuts: today | tomorrow | yesterday | one_week_ago | one_week_from_now | one_month_ago | one_month_from_now\n\nTitle keyword filtering (OR vs AND):\n- Use OR (\"operator\": \"or\") when unsure or for broad discovery.\n- Use AND (\"operator\": \"and\") when the user is specific and you want to narrow results.\n- Break multi-word phrases into individual terms and filter on each term separately.\n\nExample 1: Filter meetings from the past week (relative):\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_within\",\n \"value\": { \"type\": \"relative\", \"value\": \"the_past_week\" }\n }\n }\n ]\n }\n}\n\nExample 2: Filter meetings from the past 3 days (custom relative):\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_within\",\n \"value\": { \"type\": \"relative\", \"value\": \"custom\", \"direction\": \"past\", \"unit\": \"day\", \"count\": 3 }\n }\n }\n ]\n }\n}\n\nExample 3: Filter meetings by exact date range:\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_within\",\n \"value\": { \"type\": \"exact\", \"value\": { \"type\": \"daterange\", \"start_date\": \"2025-01-01\", \"end_date\": \"2025-12-31\" } }\n }\n }\n ]\n }\n}\n\nExample 4: Filter meetings created after a specific date:\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_after\",\n \"value\": { \"type\": \"exact\", \"value\": { \"type\": \"date\", \"start_date\": \"2025-06-01\" } }\n }\n }\n ]\n }\n}\n\nExample 5: Filter meetings by a specific attendee (use \"search\" tool first to get user ID):\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"attendees\",\n \"filter\": {\n \"operator\": \"person_contains\",\n \"value\": [\n { \"type\": \"exact\", \"value\": { \"table\": \"notion_user\", \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\" } }\n ]\n }\n }\n ]\n }\n}\n\nExample 6: Combine attendees with date range:\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_on_or_after\",\n \"value\": { \"type\": \"exact\", \"value\": { \"type\": \"date\", \"start_date\": \"2025-01-01\" } }\n }\n },\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_on_or_before\",\n \"value\": { \"type\": \"exact\", \"value\": { \"type\": \"date\", \"start_date\": \"2025-01-31\" } }\n }\n },\n {\n \"property\": \"attendees\",\n \"filter\": {\n \"operator\": \"person_contains\",\n \"value\": [\n { \"type\": \"exact\", \"value\": { \"table\": \"notion_user\", \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\" } }\n ]\n }\n }\n ]\n }\n}\n\nExample 7: Filter meetings by title content:\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"title\",\n \"filter\": {\n \"operator\": \"string_contains\",\n \"value\": { \"type\": \"exact\", \"value\": \"design review\" }\n }\n }\n ]\n }\n}\n\nExample 8: Filter meetings matching any of several title terms (using \"or\"):\n{\n \"filter\": {\n \"operator\": \"or\",\n \"filters\": [\n {\n \"property\": \"title\",\n \"filter\": {\n \"operator\": \"string_contains\",\n \"value\": { \"type\": \"exact\", \"value\": \"standup\" }\n }\n },\n {\n \"property\": \"title\",\n \"filter\": {\n \"operator\": \"string_contains\",\n \"value\": { \"type\": \"exact\", \"value\": \"sync\" }\n }\n }\n ]\n }\n}" } }, "required": ["type", "query_meeting_notes"], "title": "Query Meeting Notes" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_agents", "description": "The name of the tool to run." }, "list_agents": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional search query to filter agents by name or description (case-insensitive)." }, "start_cursor": { "type": "string", "minLength": 1, "description": "Cursor for pagination. Use the next_cursor value from the previous response to get the next page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of agents to return per page (default: 50, max: 100)." } }, "description": "The parameters for the list_agents tool. Retrieves a list of all custom agents (workflows) that the authenticated user has access to in the current workspace.\nThis tool provides visibility into available agents including their names, IDs, descriptions, and system instructions.\n\nThe optional query filters agents by case-insensitive substring match on their name and description. Results are\npaginated: when has_more is true, pass the response's next_cursor back as start_cursor to fetch the next page.\n\nThe returned data includes:\n- Agent ID\n- Agent name\n- Agent description\n- Agent system instructions\n\n\n1. List all available agents: {}\n\n2. Filter agents by name or description: {\"query\": \"customer support\"}\n\n3. Get next page of results: {\"start_cursor\": \"...\"}\n\n4. Set custom page size: {\"page_size\": 20}\n" } }, "required": ["type", "list_agents"], "title": "List Agents" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_private_pages", "description": "The name of the tool to run." }, "list_private_pages": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "description": "The parameters for the list_private_pages tool. List the current user's top-level pages and databases in their Private sidebar section. Use this to browse private workspace structure; use search when looking for content by meaning or keyword. Follow cursor pagination when the complete list is needed." } }, "required": ["type", "list_private_pages"], "title": "List Private Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_shared_pages", "description": "The name of the tool to run." }, "list_shared_pages": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "description": "The parameters for the list_shared_pages tool. List pages and databases in the current user's Shared sidebar section. Use this to browse content shared directly with the user; use search when looking for content by meaning or keyword. Follow cursor pagination when the complete list is needed." } }, "required": ["type", "list_shared_pages"], "title": "List Shared Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_favorite_pages", "description": "The name of the tool to run." }, "list_favorite_pages": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "description": "The parameters for the list_favorite_pages tool. List the current user's favorite pages and databases in sidebar order. Use this when the user refers to a favorite or pinned workspace item. Follow cursor pagination when the complete list is needed." } }, "required": ["type", "list_favorite_pages"], "title": "List Favorite Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_recent_pages", "description": "The name of the tool to run." }, "list_recent_pages": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "description": "The parameters for the list_recent_pages tool. List pages and databases the current user recently viewed, ranked by recency and visit frequency. Use this to recover likely navigation context when the user refers to something they were recently working on. Follow cursor pagination when the complete list is needed." } }, "required": ["type", "list_recent_pages"], "title": "List Recent Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "search_agents", "description": "The name of the tool to run." }, "search_agents": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["favorites", "workspace"], "description": "Which agents to list: \"favorites\" for the current user's favorite agents, or \"workspace\" for agents shared with the workspace." }, "query": { "type": "string", "description": "Search text matched against agent names and descriptions. When omitted, favorites are returned in sidebar order and workspace agents are returned newest first." }, "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "required": ["scope"], "description": "The parameters for the search_agents tool. Search agents by name or description, or browse the current user's favorite agents and the workspace's newest agents. Use this instead of list_agents when personal favorites or relevance-ranked search are needed." } }, "required": ["type", "search_agents"], "title": "Search Agents" }, { "type": "object", "properties": { "type": { "type": "string", "const": "search_sessions", "description": "The name of the tool to run." }, "search_sessions": { "type": "object", "properties": { "question": { "type": "string", "description": "What you want to find in past sessions." }, "lookback": { "type": "string", "description": "How far back to search, such as \"30d\" or \"1y\". Leave it out to search the past year." } }, "required": ["question"], "description": "The parameters for the search_sessions tool. Search past agent sessions by topic in a periodically refreshed index and return matching session URLs and excerpts. Recently created or updated sessions may not appear; use query_sessions for recent sessions." } }, "required": ["type", "search_sessions"], "title": "Search Sessions" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_sessions", "description": "The name of the tool to run." }, "query_sessions": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 2000, "description": "A case-insensitive substring search over session titles." }, "filter": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": ["created_at", "updated_at"] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "maxItems": 100, "description": "Return sessions that match every child filter.", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "maxItems": 100, "description": "Return sessions that match every child filter.", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": [ "property", "status" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "maxItems": 100, "description": "Return sessions that match any child filter.", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": [ "property", "status" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } } ] } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "maxItems": 100, "description": "Return sessions that match any child filter.", "items": { "oneOf": [ { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "string"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": ["property", "status"], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": ["property", "timestamp"], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } }, { "type": "object", "required": ["and"], "additionalProperties": false, "properties": { "and": { "type": "array", "maxItems": 100, "description": "Return sessions that match every child filter.", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": [ "property", "status" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } } ] } } } }, { "type": "object", "required": ["or"], "additionalProperties": false, "properties": { "or": { "type": "array", "maxItems": 100, "description": "Return sessions that match any child filter.", "items": { "oneOf": [ { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": [ "property", "string" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["agent_id"] }, "string": { "type": "object", "description": "An exact string comparison.", "required": ["equals"], "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this exact value." } } } } }, { "type": "object", "required": [ "property", "status" ], "additionalProperties": false, "properties": { "property": { "type": "string", "enum": ["status"] }, "status": { "type": "object", "description": "A session status comparison.", "additionalProperties": false, "properties": { "equals": { "type": "string", "description": "Return sessions with this status.", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] }, "in": { "type": "array", "description": "Return sessions with any of these statuses.", "maxItems": 7, "items": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ] } } } } } }, { "type": "object", "required": [ "property", "timestamp" ], "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The session timestamp to compare.", "enum": [ "created_at", "updated_at" ] }, "timestamp": { "type": "object", "description": "A timestamp range.", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time", "description": "Return sessions before this time." }, "after": { "type": "string", "format": "date-time", "description": "Return sessions after this time." }, "on_or_before": { "type": "string", "format": "date-time", "description": "Return sessions at or before this time." }, "on_or_after": { "type": "string", "format": "date-time", "description": "Return sessions at or after this time." } } } } } ] } } } } ] } } } } ], "description": "A session property filter, or an and/or compound filter nested up to two levels deep." }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string", "enum": ["created_at", "updated_at"], "description": "One of: `created_at`, `updated_at`" }, "direction": { "type": "string", "enum": ["ascending", "descending"], "description": "One of: `ascending`, `descending`" } }, "required": ["property", "direction"] }, "maxItems": 2, "minItems": 1, "description": "Ordered sort precedence. Defaults to updated_at descending." }, "start_cursor": { "type": "string", "description": "The continuation cursor returned by the previous page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of sessions to return. Maximum: 100." } }, "description": "The parameters for the query_sessions tool. List agent sessions available to the integration. Filter, sort, or search by title." } }, "required": ["type", "query_sessions"], "title": "Query Sessions" }, { "type": "object", "properties": { "type": { "type": "string", "const": "spawn_session", "description": "The name of the tool to run." }, "spawn_session": { "type": "object", "properties": { "agent_url": { "type": "string", "minLength": 1, "description": "Published Custom Agent URL in agent:/// format, as returned by list_agents or search_agents." }, "initial_message": { "type": "string", "minLength": 1, "description": "Initial message for the new session." } }, "required": ["agent_url", "initial_message"], "description": "The parameters for the spawn_session tool. Start a session with a published Custom Agent. Use get_session_status or wait_session to check its progress." } }, "required": ["type", "spawn_session"], "title": "Spawn Session" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_session_status", "description": "The name of the tool to run." }, "get_session_status": { "type": "object", "properties": { "session_url": { "type": "string", "minLength": 1, "description": "Custom Agent session URL." } }, "required": ["session_url"], "description": "The parameters for the get_session_status tool. Get the latest turn's status for a Custom Agent session without waiting." } }, "required": ["type", "get_session_status"], "title": "Get Session Status" }, { "type": "object", "properties": { "type": { "type": "string", "const": "wait_session", "description": "The name of the tool to run." }, "wait_session": { "type": "object", "properties": { "session_url": { "type": "string", "minLength": 1, "description": "Custom Agent session URL." }, "seconds": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Maximum number of seconds to wait." } }, "required": ["session_url", "seconds"], "description": "The parameters for the wait_session tool. Wait for the latest turn in a Custom Agent session to stop running." } }, "required": ["type", "wait_session"], "title": "Wait Session" }, { "type": "object", "properties": { "type": { "type": "string", "const": "stop_session", "description": "The name of the tool to run." }, "stop_session": { "type": "object", "properties": { "session_url": { "type": "string", "minLength": 1, "description": "Custom Agent session URL." } }, "required": ["session_url"], "description": "The parameters for the stop_session tool. Stop a running Custom Agent session you can access." } }, "required": ["type", "stop_session"], "title": "Stop Session" }, { "type": "object", "properties": { "type": { "type": "string", "const": "send_message_to_session", "description": "The name of the tool to run." }, "send_message_to_session": { "type": "object", "properties": { "session_url": { "type": "string", "minLength": 1, "description": "Custom Agent session URL." }, "message": { "type": "string", "minLength": 1, "description": "Follow-up message to send." } }, "required": ["session_url", "message"], "description": "The parameters for the send_message_to_session tool. Send a follow-up message to a Custom Agent session you can access." } }, "required": ["type", "send_message_to_session"], "title": "Send Message To Session" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_session_events", "description": "The name of the tool to run." }, "list_session_events": { "type": "object", "properties": { "session_url": { "type": "string", "minLength": 1, "description": "Custom Agent session URL." }, "count": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of committed events to return." }, "before_sequence": { "type": "integer", "minimum": 1, "description": "Load the previous page of events ending before this sequence number." }, "after_sequence": { "type": "integer", "minimum": 1, "description": "Load the next page of events starting after this sequence number." } }, "required": ["session_url", "count"], "description": "The parameters for the list_session_events tool. List short summaries of saved events in a Custom Agent session." } }, "required": ["type", "list_session_events"], "title": "List Session Events" }, { "type": "object", "properties": { "type": { "type": "string", "const": "read_session_event", "description": "The name of the tool to run." }, "read_session_event": { "type": "object", "properties": { "session_url": { "type": "string", "minLength": 1, "description": "Custom Agent session URL." }, "sequence": { "type": "integer", "minimum": 1, "description": "Committed event sequence number to read." } }, "required": ["session_url", "sequence"], "description": "The parameters for the read_session_event tool. Read the full visible content of one saved Custom Agent session event." } }, "required": ["type", "read_session_event"], "title": "Read Session Event" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_view", "description": "The name of the tool to run." }, "create_view": { "type": "object", "properties": { "data_source_id": { "type": "string", "description": "The data source (collection) ID. Accepts a collection:// URI from tags or a bare UUID." }, "name": { "type": "string", "description": "The name of the view." }, "type": { "type": "string", "enum": [ "table", "board", "list", "calendar", "timeline", "gallery", "form", "chart", "map", "dashboard" ], "description": "The type of view to create." }, "database_id": { "type": "string", "description": "The database to add a view tab to. Accepts a Notion URL or a bare UUID. Mutually exclusive with `parent_page_id`; exactly one must be provided." }, "parent_page_id": { "type": "string", "description": "A page to create an inline linked database view on. Accepts a Notion URL or a bare UUID. The new linked view block is appended at the end of the page and references `data_source_id`. Mutually exclusive with `database_id`; exactly one must be provided." }, "configure": { "type": "string", "description": "View configuration DSL string. Supports FILTER, SORT BY, GROUP BY, CALENDAR BY, TIMELINE BY, MAP BY, CHART, FORM, SHOW, HIDE, COVER, WRAP CELLS, and FREEZE COLUMNS directives. See notion://docs/view-dsl-spec." } }, "required": ["data_source_id", "name", "type"], "description": "The parameters for the create_view tool. Create a new view on a Notion database.\n\nExactly one of \"database_id\" or \"parent_page_id\" must be provided:\n- \"database_id\": add a new view tab to an existing database.\n- \"parent_page_id\": create an inline linked database view on a page that\n references the existing \"data_source_id\" (like the UI \"/linked\" command).\n The linked view block is appended to the end of the parent page.\n\nUse \"fetch\" first to get the database_id, parent_page_id, and data_source_id\n(from tags in the response). The caller must have edit access\nto the database (or parent page) and access to the data source.\n\nSupported types: table, board, list, calendar, timeline, gallery, form, chart, map, dashboard.\n\nThe optional \"configure\" param accepts a DSL for filters, sorts, grouping,\nand display options. See the notion://docs/view-dsl-spec resource for full\nsyntax (readable via your MCP client's resource-reading interface, or by\npassing the URI to the Notion \"fetch\" tool). Key directives:\n- FILTER \"Property\" = \"value\" — filter rows. Relation values must be a page\n URL or UUID; person values must be a user URI (user://), user\n UUID, or \"me\". Names are not supported for either.\n- SORT BY \"Property\" ASC — sort rows\n- GROUP BY \"Property\" — group by property (required for board views)\n- CALENDAR BY \"Property\" — date property (required for calendar views)\n- TIMELINE BY \"Start\" TO \"End\" — date range (required for timeline views)\n- MAP BY \"Property\" — location property (required for map views)\n- CHART column|bar|line|donut|number — chart type with optional AGGREGATE, COLOR, HEIGHT, SORT, STACK BY, CAPTION\n- FORM CLOSE|OPEN — close/open form submissions\n- FORM ANONYMOUS true|false — toggle anonymous submissions\n- FORM PERMISSIONS none|reader|editor — set submission permissions\n- SHOW \"Prop1\", \"Prop2\" — set visible properties\n- COVER \"Property\" — cover image property\n\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"All Tasks\", \"type\": \"table\"}\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"Task Board\", \"type\": \"board\", \"configure\": \"GROUP BY \\\"Status\\\"\"}\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"Active\", \"type\": \"table\", \"configure\": \"FILTER \\\"Status\\\" = \\\"In Progress\\\"; SORT BY \\\"Due Date\\\" ASC\"}\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"Calendar\", \"type\": \"calendar\", \"configure\": \"CALENDAR BY \\\"Due Date\\\"\"}\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"Overview\", \"type\": \"dashboard\"}\n{\"parent_page_id\": \"ghi789\", \"data_source_id\": \"def456\", \"name\": \"Company tasks\", \"type\": \"table\", \"configure\": \"FILTER \\\"Company\\\" = \\\"Acme\\\"\"}" } }, "required": ["type", "create_view"], "title": "Create View" }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_view", "description": "The name of the tool to run." }, "update_view": { "type": "object", "properties": { "view_id": { "type": "string", "description": "The view to update. Accepts a view:// URI, a Notion URL with ?v= parameter, or a bare UUID." }, "name": { "type": "string", "description": "New name for the view." }, "configure": { "type": "string", "description": "View configuration DSL string. Supports FILTER, SORT BY, GROUP BY, CALENDAR BY, TIMELINE BY, MAP BY, CHART, FORM, SHOW, HIDE, COVER, WRAP CELLS, FREEZE COLUMNS, and CLEAR directives." } }, "required": ["view_id"], "description": "The parameters for the update_view tool. Update a view's name, filters, sorts, or display configuration.\n\nUse \"fetch\" to get view IDs from database responses. Only include fields\nyou want to change. The \"configure\" param uses the same DSL as create_view.\nUse CLEAR to remove settings:\n- CLEAR FILTER — remove all filters\n- CLEAR SORT — remove all sorts\n- CLEAR GROUP BY — remove grouping\n\nSee notion://docs/view-dsl-spec resource for full syntax (readable via your\nMCP client's resource-reading interface, or by passing the URI to the Notion\n\"fetch\" tool).\n\n{\"view_id\": \"abc123\", \"name\": \"Sprint Board\"}\n{\"view_id\": \"abc123\", \"configure\": \"FILTER \\\"Status\\\" = \\\"Done\\\"\"}\n{\"view_id\": \"abc123\", \"configure\": \"CLEAR FILTER; SORT BY \\\"Created\\\" DESC\"}\n{\"view_id\": \"abc123\", \"configure\": \"GROUP BY \\\"Priority\\\"; SHOW \\\"Name\\\", \\\"Status\\\"\"}" } }, "required": ["type", "update_view"], "title": "Update View" }, { "type": "object", "properties": { "type": { "type": "string", "const": "search_emails", "description": "The name of the tool to run." }, "search_emails": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Search query string using Gmail-style search operators (e.g. from:, is:unread, newer_than:1d, after:/before:, subject:)." }, "user_email_address": { "type": "string", "minLength": 3, "maxLength": 320, "description": "The email address of the mailbox to search. Omit to use the user's default connected account." }, "count": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Number of results to return (default: 20, max: 500)." }, "page_token": { "type": "string", "minLength": 1, "description": "Pagination token from previous search results." }, "include_spam_trash": { "type": "boolean", "description": "Whether to include spam and trash in results. Defaults to false." } }, "required": ["query"], "description": "The parameters for the search_emails tool. Search the user's email inbox (their Notion Mail connected account) using\nGmail query syntax, and return matching threads with ids, participants,\ndates, and snippets.\n\nThis searches the user's personal mailbox, not Notion workspace content —\nuse the regular \"search\" tool for pages and databases. Only Gmail-backed\naccounts are supported by this tool.\n\nQuery guidance: use Gmail-style operators (from:, to:, subject:, is:unread,\nhas:attachment, newer_than:1d, after:/before:). For topic or digest requests,\nprefer recency (newer_than:1d) and/or sender (from:) filters over subject:\nkeyword filtering: subjects don't reliably contain the topic word, and when\nfiltering by subject/body cover synonyms rather than over-filtering one term.\nDate bounds after:/before: take a plain date with no time component\n(before:2026/05/08 or before:2026-05-08); a time component is not valid Gmail\nsyntax and silently returns nothing.\n\nEach result includes a threadId: a single opaque string, possibly with a\nverification stamp appended after a \".\" (e.g. 1894c2bd0f58f2b7.a83f92c1).\nPass the whole value unchanged to view-thread-content.\n\nResults may include url: a direct provider URL for opening the thread. Use it\ndirectly; never construct a provider URL from threadId or message IDs." } }, "required": ["type", "search_emails"], "title": "Search Emails" }, { "type": "object", "properties": { "type": { "type": "string", "const": "view_thread_content", "description": "The name of the tool to run." }, "view_thread_content": { "type": "object", "properties": { "thread_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The thread ID to view (from search-emails). A stamped ref is accepted as-is." }, "user_email_address": { "type": "string", "minLength": 3, "maxLength": 320, "description": "The email address of the mailbox containing the thread. Omit to use the user's default connected account." }, "most_recent_message_only": { "type": "boolean", "description": "If true (the default), returns only the most recent message. Set false to return all messages in the thread." } }, "required": ["thread_id"], "description": "The parameters for the view_thread_content tool. View the content of an email thread from the user's email inbox (their Notion\nMail connected account), including message bodies and attachment metadata.\n\nUse a threadId returned by search-emails. The id is a single opaque string; a\nverification stamp may be appended after a \".\" (e.g. 1894c2bd0f58f2b7.a83f92c1)\nand that stamp is part of the value, not a separate field — pass the whole\nvalue exactly as received.\n\nThread ids are scoped to the mailbox they were found in: if the search ran\nagainst a non-default mailbox (see searched_email_address in the search\nresult), pass that same address as user_email_address here.\n\nThe response may include url: a direct provider URL for opening the thread. Use\nit directly; never construct a provider URL from threadId or message IDs." } }, "required": ["type", "view_thread_content"], "title": "View Thread Content" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runToolResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/tools/auth": { "get": { "summary": "Authorize an AI tools session", "operationId": "authorize-tools-session", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "space_id": { "type": "string", "description": "The workspace ID for this tools session." }, "tool_names": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "The MCP tools that may be registered for this authenticated session." }, "has_advanced_tools": { "type": "boolean", "description": "Whether advanced Notion MCP tools should be registered for this authenticated session." }, "has_ai_access": { "type": "boolean", "description": "Whether AI-gated Notion MCP tools should be registered for this authenticated session." } }, "additionalProperties": false, "required": ["space_id"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/tools/run/eval": { "post": { "summary": "Run an AI tool in eval mode", "operationId": "run-tool-eval", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "eval_session_id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "The eval session ID for tracking operations across multiple tool calls." }, "eval_run_id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "The eval run ID for organizing a group of eval sessions." } }, "required": ["eval_session_id", "eval_run_id"] }, { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "search", "description": "The name of the tool to run." }, "search": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Semantic search query over your entire Notion workspace and connected sources\n(Slack, Google Drive, Github, Jira, Microsoft Teams, Sharepoint, OneDrive,\nor Linear). For best results, don't provide more than one question per tool call.\nUse a separate \"search\" tool call for each search you want to perform.\n\nAlternatively, the query can be a substring or keyword to find users by matching\nagainst their name or email address. For example: \"john\" or \"john@example.com\"" }, "query_type": { "type": "string", "enum": ["internal", "user"], "description": "Specify type of the query as either \"internal\" or \"user\". Always include this input if performing\n\"user\" search." }, "content_search_mode": { "type": "string", "enum": ["workspace_search", "ai_search"], "description": "Select search backend: \"workspace_search\" (faster, workspace-only) or \"ai_search\" (semantic, includes Slack/Linear/etc.). If omitted, uses AI search if available. Content searches only." }, "data_source_url": { "type": "string", "description": "Optionally, provide the URL of a Data source to search. This will perform a semantic search over\nthe pages in the Data Source. Note: must be a Data Source, not a Database. tags are\npart of the Notion flavored Markdown format returned by tools like fetch. The full spec is\navailable in the create-pages tool description." }, "page_url": { "type": "string", "description": "Optionally, provide the URL or ID of a page to search within. This will perform a semantic search\nover the content within and under the specified page. Accepts either a full page URL\n(e.g. https://notion.so/workspace/Page-Title-1234567890) or just the page ID (UUIDv4) with or\nwithout dashes." }, "teamspace_id": { "type": "string", "description": "Optionally, provide the ID of a teamspace to restrict search results to. This will perform a search\nover content within the specified teamspace only. Accepts the teamspace ID (UUIDv4) with or\nwithout dashes." }, "filters": { "type": "object", "properties": { "created_date_range": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "The start date of the date range as an ISO 8601 date string, if any." }, "end_date": { "type": "string", "format": "date", "description": "The end date of the date range as an ISO 8601 date string, if any." } }, "description": "Optional filter to only produce search results created within the specified date range." }, "created_by_user_ids": { "type": "array", "items": { "$ref": "#/components/schemas/idRequest" }, "maxItems": 100, "description": "Optional filter to only produce search results created by the Notion users that have the specified user IDs." } }, "description": "Optionally provide filters to apply to the search results. Only valid when query_type is 'internal'." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Maximum number of results to return (default 10). Lower values reduce response size." }, "max_highlight_length": { "type": "integer", "minimum": 0, "maximum": 500, "description": "Maximum character length for result highlights (default 200). Set to 0 to omit highlights entirely." } }, "required": ["query"], "description": "The parameters for the search tool. Search the user's Notion workspace and connected sources (Slack, Google Drive,\n\t\tGitHub, Jira, Teams, SharePoint, OneDrive, Linear) and return a ranked list\n\t\tof results to read. Two query types:\n\t\t- \"internal\" (default): content across Notion and connected sources.\n\t\t- \"user\": find people by name or email.\n\n\t\tWhen to use this vs. get-answer:\n\t\t- Use search when you want results to read, filter, cite, or fetch in full,\n\t\t or when you'll synthesize across sources yourself.\n\t\t- Use get-answer when you just want one synthesized answer and don't need\n\t\t the underlying pages. If its answer isn't good enough, come back to search\n\t\t for the full results.\n\n\t\tHow to search well:\n\t\t- One question or topic per call. Make separate calls for separate needs.\n\t\t- If the question names a person, timeframe, teamspace, or database, pass\n\t\t the matching filter. Otherwise omit filters for the broadest recall.\n\t\t- Date filter values use the YYYY-MM-DD calendar-date format.\n\t\t- Keep responses small: set page_size (default 10, max 25) and\n\t\t max_highlight_length (default 200; 0 to omit) as low as you can.\n\t\t- After finding a Notion result, call fetch with its \"id\" for full contents.\n\n\t\tThe backend is auto-selected: AI search when the user has Notion AI and\n\t\tconnectors, otherwise faster workspace-only search. Use content_search_mode\n\t\tonly when you specifically need one or the other.\n\n\t\tTo search within a database: fetch the database first to get its data source\n\t\tURL (collection://...) from tags, then pass that as\n\t\tdata_source_url. For multi-source databases, match by view ID (?v=...) or\n\t\tsearch each source. Don't combine a database URL or ID with the collection://\n\t\tprefix, and don't use a database URL as page_url.\n\n\t\t\n\t\t{\n\t\t\t\"query\": \"quarterly revenue report\",\n\t\t\t\"query_type\": \"internal\",\n\t\t\t\"filters\": {\n\t\t\t\t\"created_date_range\": {\n\t\t\t\t\t\"start_date\": \"2024-01-01\",\n\t\t\t\t\t\"end_date\": \"2025-01-01\"\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\t\n\n\t\t\n\t\t{\"query\": \"project updates\", \"query_type\": \"internal\", \"teamspace_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"filters\": {\"created_by_user_ids\": [\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"]}}\n\t\t\n\n\t\t\n\t\t{\"query\": \"design review\", \"data_source_url\": \"collection://f336d0bc-b841-465b-8045-024475c079dd\", \"filters\": {\"created_date_range\": {\"start_date\": \"2024-10-01\"}, \"created_by_user_ids\": [\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"b2c3d4e5-f6a7-8901-bcde-f12345678901\"]}}\n\t\t\n\n\t\t\n\t\t{\"query\": \"john@example.com\", \"query_type\": \"user\"}\n\t\t" } }, "required": ["type", "search"], "title": "Search" }, { "type": "object", "properties": { "type": { "type": "string", "const": "fetch", "description": "The name of the tool to run." }, "fetch": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID or URL of the Notion page, database, or data source to fetch. Supports notion.so URLs, Notion Sites URLs (*.notion.site), raw UUIDs, and data source URLs (collection://...). Pass \"self\" to fetch the connected workspace and user identity. Pass a notion://docs/* URI to read that documentation resource." }, "include_transcript": { "type": "boolean", "description": "Whether to include meeting note transcripts. Defaults to false. When true, full transcripts are included; when false, a placeholder with the meeting note URL is shown instead." }, "include_discussions": { "type": "boolean", "description": "Whether to include discussion/comment indicators in the page output. When true, adds a summary with discussion count, preview snippets, and discussion:// URLs. Use with the get_comments tool to retrieve full discussion content. Defaults to false." } }, "required": ["id"], "description": "The parameters for the fetch tool. Retrieves details about a Notion entity (page, database, or data source) by URL or ID.\n\nProvide URL or ID in `id` parameter. Make multiple calls to fetch multiple entities.\n\nPages use enhanced Markdown format. For the complete specification,\nread the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool.\n\nPass a `notion://docs/*` URI (e.g. `notion://docs/enhanced-markdown-spec` or\n`notion://docs/view-dsl-spec`) as the `id` to read that documentation resource through\nthis tool. The content is identical to the MCP resource of the same URI.\n\nDatabases return all data sources (collections). Each data source has a unique ID shown in\n`` tags. You can pass a data source ID directly to this\ntool to fetch details about that specific data source, including its schema and properties.\nUse data source IDs with update_data_source and query_data_sources tools. Multi-source\ndatabases (e.g., with linked sources) will show multiple data sources.\nIf fetching a database block ID returns a validation error, use the `collection://` data source\nURL included in that error instead.\n\nSet `include_discussions` to true to see discussion counts and inline discussion markers\nthat correlate with the `get_comments` tool. The page output will include a\n`` summary tag with discussion count, preview snippets, and\n`discussion://` URLs that match the discussion IDs returned by `get_comments`.\n\nPass the special id `\"self\"` to get the connected workspace and user identity instead of\nan entity. The result includes a `self` object with the workspace id + name and the\nauthenticated user's id, name, and email. Use this to label the connection (e.g. by\nworkspace name) or obtain a stable id for the connected workspace and user.\n\nOn MCP and RunTool surfaces, `self` also includes `current_tool_access`: a map from\ntool names to `available`, `available_with_limit` (calls can be made up to the limit included\nwith the workspace's plan), `upgrade_required`, or `not_enabled`. Entries include an\n`upgrade_url` when a workspace upgrade can change the status. Use this map to identify\nwhether calls are available, plan-limited, upgrade-gated, or disabled.\n\n{\"id\": \"https://notion.so/workspace/Page-a1b2c3d4e5f67890\"}\n{\"id\": \"12345678-90ab-cdef-1234-567890abcdef\"}\n{\"id\": \"https://myspace.notion.site/Page-Title-abc123def456\"}\n{\"id\": \"page-uuid\", \"include_discussions\": true}\n{\"id\": \"collection://12345678-90ab-cdef-1234-567890abcdef\"}\n{\"id\": \"self\"}\n{\"id\": \"notion://docs/enhanced-markdown-spec\"}" } }, "required": ["type", "fetch"], "title": "Fetch" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_pages", "description": "The name of the tool to run." }, "create_pages": { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] }, "description": "The properties of the new page, which is a JSON map of property names to SQLite values.\nFor pages in a database, use the SQLite schema definition shown in .\nFor pages outside of a database, the only allowed property is \"title\", which is the title of the page and is automatically shown at the top of the page as a large heading." }, "content": { "type": "string", "description": "The content of the new page, using Notion Markdown." }, "template_id": { "type": "string", "description": "The ID of a template to apply to this page. When specified, do not provide 'content' as the template will provide it. Properties can still be set alongside the template. Get template IDs from the section in the fetch tool results." }, "icon": { "type": "string", "description": "An emoji character (e.g. \"🚀\"), a custom emoji by name (e.g. \":rocket_ship:\"), or an external image URL. Use \"none\" to explicitly set no icon. Omit to leave unchanged." }, "cover": { "type": "string", "description": "An external image URL for the page cover. Use \"none\" to explicitly set no cover. Omit to leave unchanged." } }, "additionalProperties": false }, "maxItems": 100, "description": "The pages to create." }, "parent": { "oneOf": [ { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the parent page (with or without dashes), for example, 195de9221179449fab8075a27c979105" }, "type": { "type": "string", "const": "page_id", "description": "Always `page_id`" } }, "required": ["page_id"] }, { "type": "object", "properties": { "database_id": { "type": "string", "description": "The ID of the parent database (with or without dashes), for example, 195de9221179449fab8075a27c979105" }, "type": { "type": "string", "const": "database_id", "description": "Always `database_id`" } }, "required": ["database_id"] }, { "type": "object", "properties": { "data_source_id": { "type": "string", "description": "The ID of the parent data source (collection), with or without dashes. For example, f336d0bc-b841-465b-8045-024475c079dd" }, "type": { "type": "string", "const": "data_source_id", "description": "Always `data_source_id`" } }, "required": ["data_source_id"] } ], "description": "The parent under which the new pages will be created. This can be a page (page_id), a database page (database_id), or a data source/collection under a database (data_source_id). If omitted, the new pages will be created as private pages at the workspace level. Use data_source_id when you have a collection:// URL from the fetch tool." }, "allow_async": { "type": "boolean", "description": "Set to true to opt into receiving an async_task result when this create operation is accepted for background execution. If omitted or false, the tool keeps the existing synchronous result shape." } }, "required": ["pages"], "description": "The parameters for the create_pages tool. ## Overview\n\n\t\tCreates one or more Notion pages, with the specified properties and content.\n\n\t\t## Parent\n\n\t\tAll pages created with a single call to this tool will have the same parent.\n\t\tThe parent can be a Notion page (\"page_id\") or data source (\"data_source_id\").\n\t\tIf the parent is omitted, the pages are created as standalone, workspace-level\n\t\tprivate pages, and the person that created them can organize them later as they\n\t\tsee fit.\n\n\t\tIf you have a database URL, ALWAYS pass it to the \"fetch\" tool first to get the schema\n\t\tand URLs of each data source under the database. You can't use the \"database_id\"\n\t\tparent type if the database has more than one data source, so you'll need to identify\n\t\twhich \"data_source_id\" to use based on the situation and the results from the fetch tool\n\t\t(data source URLs look like collection://).\n\n\t\tIf you know the pages should be created under a data source, do NOT use the database ID\n\t\tor URL under the \"page_id\" parameter; \"page_id\" is only for regular, non-database pages.\n\n\t\t## Content\n\n\t\tNotion page content is a string in Notion-flavored Markdown format.\n\n\t\tDon't include the page title at the top of the page's content. Only include it under\n\t\t\"properties\".\n\n\t\t**IMPORTANT**: For the complete Markdown specification, always first\n\t\tread the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool.\n\t\tDo NOT guess or hallucinate Markdown syntax.\n\t\tThis spec is also applicable to other tools like update-page and fetch.\n\n\t\t## Properties\n\n\t\tNotion page properties are a JSON map of property names to SQLite values.\n\n\t\tWhen creating pages in a database:\n\t\t- Use the correct property names from the data source schema shown in the fetch tool results.\n\t\t- Always include a title property. Data sources always have exactly one title property, but\n\t\t it may not be named \"title\", so, again, rely on the fetched data source schema.\n\n\t\tFor pages outside of a database:\n\t\t- The only allowed property is \"title\",\twhich is the title of the page in inline markdown format.\n\t\t Always include a \"title\" property.\n\n\t\t**IMPORTANT**: Some property types require specific formats:\n\t- Date properties: Split into \"date:{property}:start\", \"date:{property}:end\" (optional), and\n\t \"date:{property}:is_datetime\" (0 or 1)\n\t- Place properties: Split into \"place:{property}:name\", \"place:{property}:address\",\n\t \"place:{property}:latitude\", \"place:{property}:longitude\", and\n\t \"place:{property}:google_place_id\" (optional)\n\t- Number properties: Use JavaScript numbers (not strings)\n\t- Checkbox properties: Use \"__YES__\" for checked, \"__NO__\" for unchecked\n\t- Relation properties: Use an array of related page URLs or page IDs, e.g.\n\t [\"https://www.notion.so/26ab1f9f4c5f80b18d3bd10a6b1d2f4e\", \"26ab1f9f-4c5f-80b1-8d3b-d10a6b1d2f4e\"]\n\t- Files properties: Use a JSON array of file IDs, Notion Folder URLs, and/or tags\n\t copied from fetch output. Folders are stored as native Folder references, not ordinary links.\n\n\t**Special property naming**: Properties named \"id\" or \"url\" (case insensitive) must be\n\tprefixed with \"userDefined:\" (e.g., \"userDefined:URL\", \"userDefined:id\")\n\n\t\t## Templates\n\n\t\tWhen creating a page in a database, you can apply a template to pre-populate it with\n\t\tcontent and property values. Use the \"fetch\" tool on a database to see available\n\t\ttemplates in the section of each data source.\n\n\t\tWhen using a template:\n\t\t- Pass the template's ID as \"template_id\" in the page object.\n\t\t- Do NOT include \"content\" when using a template, as the template provides it.\n\t\t- You can still set \"properties\" alongside the template to override template defaults.\n\t\t- Template application is asynchronous. The page is created immediately but starts\n\t\t blank; the template content will appear shortly after.\n\n\t\t## Icon and Cover\n\n\t\tEach page can optionally have an icon and a cover image.\n\t\t- \"icon\": An emoji character (e.g. \"🚀\"), a custom emoji by name (e.g. \":rocket_ship:\"),\n\t\t or an external image URL. Use \"none\" to remove. Omit to leave unchanged.\n\t\t- \"cover\": An external image URL. Use \"none\" to remove. Omit to leave unchanged.\n\n\t\t## Examples\n\n\t\t\n\t\t{\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"properties\": {\"title\": \"My Page\"},\n\t\t\t\t\t\"icon\": \"🚀\",\n\t\t\t\t\t\"cover\": \"https://example.com/cover.jpg\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"parent\": {\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\"},\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"template_id\": \"a5da15f6-b853-455d-8827-f906fb52db2b\",\n\t\t\t\t\t\"properties\": {\n\t\t\t\t\t\t\"Task Name\": \"New urgent bug\"\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"properties\": {\"title\": \"Page title\"},\n\t\t\t\t\t\"content\": \"# Section 1 {color=\"blue\"}\nSection 1 content\n
\nToggle block\n\tHidden content inside toggle\n
\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"parent\": {\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\"},\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"properties\": {\n\t\t\t\t\t\t\"Task Name\": \"Task 123\",\n\t\t\t\t\t\t\"Status\": \"In Progress\",\n\t\t\t\t\t\t\"Priority\": 5,\n\t\t\t\t\t\t\"Is Complete\": \"__YES__\",\n\t\t\t\t\t\t\"date:Due Date:start\": \"2024-12-25\",\n\t\t\t\t\t\t\"date:Due Date:is_datetime\": 0\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"parent\": {\"page_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"},\n\t\t\t\"pages\": [\n\t\t\t\t{\n\t\t\t\t\t\"properties\": {\"title\": \"Page title\"},\n\t\t\t\t\t\"content\": \"# Section 1\n\nSection 1 content\n\n# Section 2\n\nSection 2 content\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t## Async support\n\n\t\tSet \"allow_async\" to true to opt into receiving an async task result when\n\t\tthis create operation is accepted for background execution. If this field\n\t\tis omitted or false, the tool keeps the existing synchronous result shape." } }, "required": ["type", "create_pages"], "title": "Create Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_page", "description": "The name of the tool to run." }, "update_page": { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page to update, with or without dashes." }, "command": { "type": "string", "enum": [ "update_properties", "update_content", "replace_content", "insert_content", "apply_template", "update_verification" ], "description": "The update command to execute." }, "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] }, "description": "Required for \"update_properties\" command. A JSON object that updates the page's properties.\nFor pages in a database, use the SQLite schema definition shown in .\nFor pages outside of a database, the only allowed property is \"title\", which is the title of the page in inline markdown format.\nUse null to remove a property's value." }, "new_str": { "type": "string", "description": "Required for \"replace_content\" command. The new content string to replace the entire page content with." }, "content": { "type": "string", "description": "Required for \"insert_content\" command. The markdown content to insert into the page." }, "content_updates": { "type": "array", "items": { "type": "object", "properties": { "old_str": { "type": "string", "description": "The existing content string to find and replace. Must exactly match the page content." }, "new_str": { "type": "string", "description": "The new content string to replace old_str with." }, "replace_all_matches": { "type": "boolean", "description": "If true, replaces all occurrences of old_str. If false (default), the operation fails if there are multiple matches." } }, "required": ["old_str", "new_str"] }, "maxItems": 100, "description": "Required for \"update_content\" command. An array of search-and-replace operations, each with old_str (content to find) and new_str (replacement content)." }, "position": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "start", "description": "Insert the content at the start of the page." } }, "required": ["type"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "end", "description": "Insert the content at the end of the page." } }, "required": ["type"] } ], "description": "Optional for \"insert_content\" command. Use {\"type\":\"start\"} to prepend content or {\"type\":\"end\"} to append content. Omit to append." }, "allow_deleting_content": { "type": "boolean", "description": "Optional for \"replace_content\" and \"update_content\" commands. Set to true to allow deletion of child pages and databases that are not referenced in the new content. If false or omitted, the operation will fail with an error listing the pages/databases that would be deleted." }, "template_id": { "type": "string", "description": "Required for \"apply_template\" command. The ID of a template to apply to this page. Template content is appended to any existing page content." }, "verification_status": { "type": "string", "enum": ["verified", "unverified"], "description": "Required for \"update_verification\" command. Set to \"verified\" to mark the page as verified, or \"unverified\" to remove verification. When updating verification, the owner will be automatically set to the authenticated actor." }, "verification_expiry_days": { "type": "integer", "minimum": 1, "description": "Optional for \"update_verification\" command when verification_status is \"verified\". Number of days until verification expires (e.g. 7, 30, 90). Omit for indefinite verification." }, "icon": { "type": "string", "description": "An emoji character (e.g. \"🚀\"), a custom emoji by name (e.g. \":rocket_ship:\"), or an external image URL. Use \"none\" to remove the icon. Omit to leave unchanged. Can be set alongside any command." }, "cover": { "type": "string", "description": "An external image URL for the page cover. Use \"none\" to remove the cover. Omit to leave unchanged. Can be set alongside any command." }, "is_skill": { "type": "boolean", "description": "Set to true to mark this page as an AI skill, or false to remove the AI skill designation. Can be set alongside any command." }, "allow_async": { "type": "boolean", "description": "Optional. Set to true to opt into an async_task response after the update_page request is validated, durably persisted, and accepted for queued execution. If omitted or false, the tool waits for a synchronous result when possible, but may still return a pollable async_task response if queued execution exceeds the synchronous wait deadline." } }, "required": ["page_id", "command"], "description": "The parameters for the update_page tool. ## Overview\n\n\t\tUpdate a Notion page's properties or content.\n\n\t\t## Properties\n\n\t\tNotion page properties are a JSON map of property names to SQLite values.\n\n\t\tFor pages in a database:\n\t\t- ALWAYS use the \"fetch\" tool first to get the data source schema and the\texact property names.\n\t\t- Provide a non-null value to update a property's value.\n\t\t- Omitted properties are left unchanged.\n\n\t\t**IMPORTANT**: Some property types require specific formats:\n\t- Date properties: Split into \"date:{property}:start\", \"date:{property}:end\" (optional), and\n\t \"date:{property}:is_datetime\" (0 or 1)\n\t- Place properties: Split into \"place:{property}:name\", \"place:{property}:address\",\n\t \"place:{property}:latitude\", \"place:{property}:longitude\", and\n\t \"place:{property}:google_place_id\" (optional)\n\t- Number properties: Use JavaScript numbers (not strings)\n\t- Checkbox properties: Use \"__YES__\" for checked, \"__NO__\" for unchecked\n\t- Relation properties: Use an array of related page URLs or page IDs, e.g.\n\t [\"https://www.notion.so/26ab1f9f4c5f80b18d3bd10a6b1d2f4e\", \"26ab1f9f-4c5f-80b1-8d3b-d10a6b1d2f4e\"]\n\t- Files properties: Use a JSON array of file IDs, Notion Folder URLs, and/or tags\n\t copied from fetch output. Folders are stored as native Folder references, not ordinary links.\n\n\t**Special property naming**: Properties named \"id\" or \"url\" (case insensitive) must be\n\tprefixed with \"userDefined:\" (e.g., \"userDefined:URL\", \"userDefined:id\")\n\n\t\tFor pages outside of a database:\n\t\t- The only allowed property is \"title\",\twhich is the title of the page in inline markdown format.\n\n\t\t## Content\n\n\t\tNotion page content is a string in Notion-flavored Markdown format.\n\n\t\t**IMPORTANT**: For the complete Markdown specification, first\n\t\tread the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool.\n\t\tDo NOT guess or hallucinate Markdown syntax.\n\n\t\tFor small edits, send the smallest edit region that captures the intended change. Prefer\n\t\t\"update_content\" for targeted search-and-replace edits, or \"insert_content\" when you only\n\t\tneed to prepend or append content. Avoid full-page \"replace_content\" when \"update_content\"\n\t\tor \"insert_content\" is sufficient, because resubmitting unchanged page content makes the\n\t\toperation slower and more likely to hit async processing limits.\n\n\t\tUse \"insert_content\" to add content at the beginning or end of a page. If position is omitted,\n\t\tthe content is appended to the end of the page.\n\n\t\tBefore using \"update_content\", use the \"fetch\" tool first to get the existing content and find\n\t\tthe Markdown snippets to use in the \"update_content\" command's old_str fields.\n\n\t\t### Preserving Child Pages and Databases\n\n\t\tWhen using \"replace_content\", the operation will check if any\n\t\tchild pages or databases would be deleted. If so, it will fail with an error listing the\n\t\taffected items.\n\n\t\tTo preserve child pages/databases, include them in new_str using `` or\n\t\t`` tags. Get the exact URLs from the \"fetch\" tool output.\n\n\t\t**CRITICAL**: To intentionally delete child content:\n\t\tif the call failed with validation and requires `allow_deleting_content` to be true,\n\t\tDO NOT automatically assume the content should be deleted.\n\t\tALWAYS show the list of pages to be deleted and ask for user confirmation before proceeding.\n\n\t\t## Icon and Cover\n\n\t\tYou can set or remove a page's icon and cover alongside any command.\n\t\t- \"icon\": An emoji character (e.g. \"🚀\"), a custom emoji by name (e.g. \":rocket_ship:\"),\n\t\t or an external image URL. Use \"none\" to remove. Omit to leave unchanged.\n\t\t- \"cover\": An external image URL. Use \"none\" to remove. Omit to leave unchanged.\n\n\t\t## AI skills\n\n\t\tSet `is_skill` to `true` to mark the page as an AI skill, or `false` to remove the\n\t\tAI skill designation. This can be set alongside any command. To change only the skill\n\t\tstatus without making another page change, use the\n\t\t`update_properties` command and omit `properties`.\n\n\t\t## Examples\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_properties\",\n\t\t\t\"properties\": {\"title\": \"My Page\"},\n\t\t\t\"icon\": \"🚀\",\n\t\t\t\"cover\": \"https://example.com/cover.jpg\"\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_properties\",\n\t\t\t\"properties\": {\n\t\t\t\t\"title\": \"New Page Title\",\n\t\t\t\t\"status\": \"In Progress\",\n\t\t\t\t\"priority\": 5,\n\t\t\t\t\"checkbox\": \"__YES__\",\n\t\t\t\t\"related_tasks\": [\"26ab1f9f-4c5f-80b1-8d3b-d10a6b1d2f4e\"],\n\t\t\t\t\"date:deadline:start\": \"2024-12-25\",\n\t\t\t\t\"date:deadline:is_datetime\": 0,\n\t\t\t\t\"place:office:name\": \"HQ\",\n\t\t\t\t\"place:office:latitude\": 37.7749,\n\t\t\t\t\"place:office:longitude\": -122.4194\n\t\t\t}\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"replace_content\",\n\t\t\t\"new_str\": \"# New Section\\nUpdated content goes here\"\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_content\",\n\t\t\t\"content_updates\": [\n\t\t\t\t{\n\t\t\t\t\t\"old_str\": \"# Old Section\\nOld content here\",\n\t\t\t\t\t\"new_str\": \"# New Section\\nUpdated content goes here\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"insert_content\",\n\t\t\t\"content\": \"## Latest update\\n\\nStatus update goes here\",\n\t\t\t\"position\": { \"type\": \"start\" }\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_content\",\n\t\t\t\"content_updates\": [\n\t\t\t\t{\n\t\t\t\t\t\"old_str\": \"## Previous section\\nExisting content\",\n\t\t\t\t\t\"new_str\": \"## Previous section\\nExisting content\\n\\n## New Section\\nContent to insert goes here\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_content\",\n\t\t\t\"content_updates\": [\n\t\t\t\t{\n\t\t\t\t\t\"old_str\": \"Old text 1\",\n\t\t\t\t\t\"new_str\": \"New text 1\"\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"old_str\": \"Old text 2\",\n\t\t\t\t\t\"new_str\": \"New text 2\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t\t\n\n\t\t## Templates\n\n\t\tYou can apply a template to an existing page using the \"apply_template\" command.\n\t\tThe template content is appended to the page asynchronously. Get template IDs from\n\t\tthe section in the fetch tool results for a database, or use any page ID\n\t\tas a template.\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"apply_template\",\n\t\t\t\"template_id\": \"a5da15f6-b853-455d-8827-f906fb52db2b\"\n\t\t}\n\t\t\n\n\t\t## Verification\n\n\t\tYou can verify or unverify a page using the \"update_verification\" command.\n\t\tVerification marks a page as reviewed and up-to-date. Requires a Business or Enterprise\n\t\tplan (or the page must be in a wiki).\n\n\t\tWhen updating verification, the owner will be automatically set to the authenticated actor.\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_verification\",\n\t\t\t\"verification_status\": \"verified\",\n\t\t\t\"verification_expiry_days\": 90\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_verification\",\n\t\t\t\"verification_status\": \"verified\"\n\t\t}\n\t\t\n\n\t\t\n\t\t{\n\t\t\t\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\",\n\t\t\t\"command\": \"update_verification\",\n\t\t\t\"verification_status\": \"unverified\"\n\t\t}\n\t\t" } }, "required": ["type", "update_page"], "title": "Update Page" }, { "type": "object", "properties": { "type": { "type": "string", "const": "convert_page_to_skill", "description": "The name of the tool to run." }, "convert_page_to_skill": { "type": "object", "properties": { "page_url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri", "description": "The full Notion URL of the page to mark as an AI skill." } }, "required": ["page_url"], "description": "The parameters for the convert_page_to_skill tool. Mark a Notion page as an AI skill. The page must be in the current workspace, and the authenticated user must have permission to edit it. Use this tool only when the user wants the page to become a skill." } }, "required": ["type", "convert_page_to_skill"], "title": "Convert Page To Skill" }, { "type": "object", "properties": { "type": { "type": "string", "const": "move_pages", "description": "The name of the tool to run." }, "move_pages": { "type": "object", "properties": { "page_or_database_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "description": "An array of up to 100 page or database IDs to move. IDs are v4 UUIDs and can be supplied with or without dashes (e.g. extracted from a or URL given by the \"search\" or \"fetch\" tool). Data Sources under Databases can't be moved individually." }, "new_parent": { "oneOf": [ { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the parent page (with or without dashes), for example, 195de9221179449fab8075a27c979105" }, "type": { "type": "string", "const": "page_id", "description": "Always `page_id`" } }, "required": ["page_id"] }, { "type": "object", "properties": { "database_id": { "type": "string", "description": "The ID of the parent database (with or without dashes), for example, 195de9221179449fab8075a27c979105" }, "type": { "type": "string", "const": "database_id", "description": "Always `database_id`" } }, "required": ["database_id"] }, { "type": "object", "properties": { "data_source_id": { "type": "string", "description": "The ID of the parent data source (collection), with or without dashes. For example, f336d0bc-b841-465b-8045-024475c079dd" }, "type": { "type": "string", "const": "data_source_id", "description": "Always `data_source_id`" } }, "required": ["data_source_id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "workspace", "description": "The parent type." } }, "required": ["type"] } ], "description": "The new parent under which the pages will be moved. This can be a page, the workspace, a database, or a specific data source under a database when there are multiple. Moving pages to the workspace level adds them as private pages and should rarely be used." } }, "required": ["page_or_database_ids", "new_parent"], "description": "The parameters for the move_pages tool. Move one or more Notion pages or databases to a new parent." } }, "required": ["type", "move_pages"], "title": "Move Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "duplicate_page", "description": "The name of the tool to run." }, "duplicate_page": { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page to duplicate. This is a v4 UUID, with or without dashes, and can be parsed from a Notion page URL." } }, "required": ["page_id"], "description": "The parameters for the duplicate_page tool. Duplicate a Notion page. The page must be within the current workspace, and you must have permission to access it. The duplication completes asynchronously, so do not rely on the new page identified by the returned ID or URL to be populated immediately. Let the user know that the duplication is in progress and that they can check back later using the 'fetch' tool or by clicking the returned URL and viewing it in the Notion app." } }, "required": ["type", "duplicate_page"], "title": "Duplicate Page" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_database", "description": "The name of the tool to run." }, "create_database": { "allOf": [ { "type": "object", "properties": { "parent": { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the parent page, with or without dashes." }, "type": { "type": "string", "const": "page_id", "description": "Always `page_id`" } }, "required": ["page_id"], "description": "The parent under which to create the new database. If omitted, the database will be created as a private page at the workspace level." }, "title": { "type": "string", "description": "The title of the new database." }, "description": { "type": "string", "description": "The description of the new database." } } }, { "oneOf": [ { "type": "object", "properties": { "schema": { "type": "string", "description": "SQL DDL CREATE TABLE statement defining the database schema. Cannot be combined with database_type. Column names must be double-quoted and type options use single quotes." } }, "required": ["schema"] }, { "type": "object", "properties": { "database_type": { "type": "string", "enum": ["tasks", "projects", "skills"], "description": "Create a typed database with Notion's canonical required properties and metadata. Supported types: tasks, projects, skills." } }, "required": ["database_type"] } ] } ], "description": "The parameters for the create_database tool. Creates a new Notion database using SQL DDL syntax, or a typed database using\nNotion's canonical schema for tasks, projects, or skills.\n\nProvide exactly one of:\n- schema: a CREATE TABLE statement. If no title property is provided, \"Name\" is auto-added.\n- database_type: one of tasks, projects, or skills. The database is created with\n the canonical required properties and typed metadata used by Notion.\n\nReturns Markdown with schema, SQLite definition, and data source ID in\n tag for use with update_data_source and query_data_sources tools.\n\nType syntax:\n- Simple: TITLE, RICH_TEXT, DATE, PEOPLE, CHECKBOX, URL, EMAIL, PHONE_NUMBER, STATUS, FILES\n- SELECT('opt':color, ...) / MULTI_SELECT('opt':color, ...)\n- NUMBER [FORMAT 'dollar'] / FORMULA('expression')\n- RELATION('data_source_id') — one-way relation\n- RELATION('data_source_id', DUAL) — two-way relation\n- RELATION('data_source_id', DUAL 'synced_name') — two-way with synced property name\n- RELATION('data_source_id', DUAL 'synced_name' 'synced_id') — two-way with synced name and ID (for self-relations)\n- ROLLUP('rel_prop', 'target_prop', 'function')\n- UNIQUE_ID [PREFIX 'X'] / CREATED_TIME / LAST_EDITED_TIME\n- Any column: COMMENT 'description text'\nColors: default, gray, brown, orange, yellow, green, blue, purple, pink, red\n\n{\"schema\": \"CREATE TABLE (\\\"Name\\\" TITLE)\"}\n{\"database_type\": \"tasks\", \"title\": \"Tasks\"}\n{\"parent\": {\"page_id\": \"f336d0bc-b841-465b-8045-024475c079dd\"}, \"title\": \"Projects\", \"schema\": \"CREATE TABLE (\\\"Name\\\" TITLE, \\\"Budget\\\" NUMBER FORMAT 'dollar', \\\"Tags\\\" MULTI_SELECT('eng':blue, 'design':pink), \\\"Task ID\\\" UNIQUE_ID PREFIX 'PRJ')\"}\n{\"title\": \"Tasks\", \"schema\": \"CREATE TABLE (\\\"Name\\\" TITLE, \\\"Parent\\\" RELATION('ds_id', DUAL 'Children' 'children'), \\\"Children\\\" RELATION('ds_id', DUAL 'Parent' 'parent'))\"}" } }, "required": ["type", "create_database"], "title": "Create Database" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_folder", "description": "The name of the tool to run." }, "create_folder": { "type": "object", "properties": { "parent": { "oneOf": [ { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page that will own the Folder." } }, "additionalProperties": false, "required": ["page_id"] }, { "type": "object", "properties": { "folder_id": { "type": "string", "description": "The ID of the Folder that will contain the new Folder." } }, "additionalProperties": false, "required": ["folder_id"] } ], "description": "Where to create the Folder." }, "title": { "type": "string", "description": "The title of the new Folder." } }, "required": ["parent", "title"], "description": "The parameters for the create_folder tool. Creates an empty Notion Folder. Set parent.page_id for a top-level Folder owned\nby a page, or parent.folder_id to create a nested Folder inside another Folder.\nA page-owned Folder is not inserted into the page's content. A nested Folder is\nappended to its parent Folder's content. The Folder inherits access from its\nparent.\n\nThis tool creates only the empty Folder. It is non-idempotent and creates a new\nFolder on every successful call." } }, "required": ["type", "create_folder"], "title": "Create Folder" }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_folder", "description": "The name of the tool to run." }, "update_folder": { "type": "object", "properties": { "folder_id": { "type": "string", "description": "The ID of the Folder to update." }, "command": { "type": "string", "enum": [ "add_files", "remove_files", "add_subfolder" ], "description": "The Folder update to apply." }, "file_upload_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "uniqueItems": true, "description": "Required for add_files. One or more file upload IDs returned by the file upload tools." }, "file_urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "uniqueItems": true, "description": "Required for remove_files. The exact file URLs shown in the Folder's latest fetch output." }, "title": { "type": "string", "description": "Required for add_subfolder. The new Folder's title." } }, "additionalProperties": false, "required": ["folder_id", "command"], "description": "The parameters for the update_folder tool. Update an existing Notion Folder with an explicit Folder operation.\n\n- Use add_files with file upload IDs returned by the upload tools.\n- Fetch the Folder first, then use remove_files with the exact file URLs from\n that fetch result.\n- Use add_subfolder to create and insert a new nested Folder.\n\nUse exactly one command shape; do not mix their arguments:\n- {\"command\":\"add_files\",\"file_upload_ids\":[\"...\"]}\n- {\"command\":\"remove_files\",\"file_urls\":[\"...\"]}\n- {\"command\":\"add_subfolder\",\"title\":\"...\"}\n\nThe Folder ID may be provided with or without dashes." } }, "required": ["type", "update_folder"], "title": "Update Folder" }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_data_source", "description": "The name of the tool to run." }, "update_data_source": { "type": "object", "properties": { "data_source_id": { "type": "string", "description": "The data source to update. Accepts a collection:// URI from tags, a bare UUID, or a database ID (only if the database has a single data source)." }, "statements": { "type": "string", "description": "Semicolon-separated SQL DDL statements to update the schema. Supports ADD COLUMN, DROP COLUMN, RENAME COLUMN, ALTER COLUMN SET." }, "title": { "type": "string", "description": "The new title of the data source." }, "description": { "type": "string", "description": "The new description of the data source." }, "is_inline": { "type": "boolean", "description": "Whether the database should display inline (true) or as full page (false). Only applicable for single-source databases." }, "in_trash": { "type": "boolean", "description": "Move data source to trash. Cannot be undone without Notion UI." } }, "required": ["data_source_id"], "description": "The parameters for the update_data_source tool. Update a Notion data source's schema, title, or attributes using SQL DDL statements.\nReturns Markdown showing updated structure and schema.\n\nAccepts a data source ID (collection ID from fetch response's tag)\nor a single-source database ID. Multi-source databases require the specific\ndata source ID.\n\nThe statements param accepts semicolon-separated DDL statements:\n- ADD COLUMN \"Name\" - add a new property\n- DROP COLUMN \"Name\" - remove a property\n- RENAME COLUMN \"Old\" TO \"New\" - rename a property\n- ALTER COLUMN \"Name\" SET - change type/options\n\nSame type syntax as create_database. Key types:\n- SELECT('opt':color, ...) / MULTI_SELECT('opt':color, ...)\n- NUMBER [FORMAT 'dollar'] / FORMULA('expression')\n- RELATION('ds_id') / RELATION('ds_id', DUAL) / RELATION('ds_id', DUAL 'synced_name' 'synced_id')\n- ROLLUP('rel_prop', 'target_prop', 'function') / UNIQUE_ID [PREFIX 'X']\n- Simple: TITLE, RICH_TEXT, DATE, PEOPLE, CHECKBOX, URL, EMAIL, PHONE_NUMBER, STATUS, FILES\n\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"statements\": \"ADD COLUMN \\\"Priority\\\" SELECT('High':red, 'Medium':yellow, 'Low':green); ADD COLUMN \\\"Due Date\\\" DATE\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"statements\": \"RENAME COLUMN \\\"Status\\\" TO \\\"Project Status\\\"\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"statements\": \"DROP COLUMN \\\"Old Property\\\"\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"statements\": \"ADD COLUMN \\\"Parent\\\" RELATION('f336d0bc-b841-465b-8045-024475c079dd', DUAL 'Children' 'children'); ADD COLUMN \\\"Children\\\" RELATION('f336d0bc-b841-465b-8045-024475c079dd', DUAL 'Parent' 'parent')\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"title\": \"Project Tracker 2024\"}\n{\"data_source_id\": \"f336d0bc-b841-465b-8045-024475c079dd\", \"in_trash\": true}\n\nNotes: Cannot delete/create title properties. Max one unique_id property.\nCannot update synced databases. Use \"fetch\" first to see current schema\nand get the data source ID from tags." } }, "required": ["type", "update_data_source"], "title": "Update Data Source" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_comment", "description": "The name of the tool to run." }, "create_comment": { "allOf": [ { "type": "object", "properties": { "page_id": { "type": "string", "description": "The ID of the page to comment on (with or without dashes)." }, "discussion_id": { "type": "string", "description": "The ID or URL of an existing discussion to reply to (e.g., discussion://pageId/blockId/discussionId)." }, "selection_with_ellipsis": { "type": "string", "description": "Unique start and end snippet of the content to comment on.\nDO NOT provide the entire string. Instead, provide up to the first ~10 characters, an ellipsis, and then up to the last ~10 characters.\nMake sure you provide enough of the start and end snippet to uniquely identify the content.\nFor example: \"# Section heading...last paragraph.\"" } }, "required": ["page_id"] }, { "oneOf": [ { "type": "object", "properties": { "rich_text": { "type": "array", "items": { "$ref": "#/components/schemas/richTextItemRequest" }, "maxItems": 100, "description": "An array of rich text objects that represent the content of the comment. Provide exactly one of rich_text or markdown." } }, "required": ["rich_text"] }, { "type": "object", "properties": { "markdown": { "type": "string", "description": "The content of the comment as a Markdown string. Provide exactly one of markdown or rich_text. For exact syntax, read the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool. Use only the Rich text types and Mentions syntax that comments support. Comments support inline formatting (bold, italic, strikethrough, underline, code, links), inline math using $`Equation`$, and user/page/database/date mention tags such as . To attach a file created by create-file-upload or create-attachment, include its returned suggested_markdown on a separate line; up to three file attachments are supported. Do not use UI shortcuts like @today, @name, [[page]], or autocomplete-style emoji syntax; those are editor affordances, not markdown syntax. Mention tags must include a real url where required by the spec. Other block-level Markdown such as fenced code blocks, headings, lists, tables, and blockquotes is stored as plain comment text rather than rendered as blocks." } }, "required": ["markdown"] } ] } ], "description": "The parameters for the create_comment tool. Add a comment to a page or specific content.\n\nCreates a new comment. Provide `page_id` to identify the page, then choose ONE targeting mode:\n- `page_id` alone: Page-level comment on the entire page\n- `page_id` + `selection_with_ellipsis`: Comment on specific block content\n- `discussion_id`: Reply to an existing discussion thread (page_id is still required)\n\nProvide exactly one content format:\n- `markdown`: Preferred. Inline Notion-flavored Markdown for comment text. For exact syntax, read the MCP resource `notion://docs/enhanced-markdown-spec` through your MCP client's resource-reading interface, or call the Notion \"fetch\" tool with this URI if your client does not support reading MCP resources. Do NOT pass this URI to any other URL-fetching tool. Use only the Rich text types and Mentions syntax that comments support. Comments support inline formatting (bold, italic, strikethrough, underline, code, links), inline math using `$`Equation`$`, and user/page/database/date mention tags such as ``. To attach a file created by `create-file-upload` or `create-attachment`, include its returned `suggested_markdown` on a separate line; up to three file attachments are supported. Do not use UI shortcuts like `@today`, `@name`, `[[page]]`, or autocomplete-style emoji syntax; those are editor affordances, not markdown syntax. Mention tags must include a real `url` where required by the spec. Other block-level Markdown such as headings, lists, tables, blockquotes, and fenced code blocks is stored as plain comment text rather than rendered as blocks.\n- `rich_text`: Array of rich text objects.\n\nFor content targeting, use `selection_with_ellipsis` with ~10 chars from start and end: \"# Section Ti...tle content\"\n\n\n{\"page_id\": \"uuid\", \"markdown\": \"Comment with **important** context.\"}\n\n\n{\"page_id\": \"uuid\", \"selection_with_ellipsis\": \"# Meeting No...es heading\",\n \"markdown\": \"Comment on this section.\"}\n\n\n{\"page_id\": \"uuid\", \"discussion_id\": \"discussion://pageId/blockId/discussionId\",\n \"markdown\": \"Reply with [context](https://example.com).\"}\n" } }, "required": ["type", "create_comment"], "title": "Create Comment" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_comments", "description": "The name of the tool to run." }, "get_comments": { "type": "object", "properties": { "page_id": { "type": "string", "description": "Identifier for a Notion page." }, "include_resolved": { "type": "boolean", "description": "Include resolved discussions in the response. Defaults to false." }, "include_all_blocks": { "type": "boolean", "description": "Include discussions on child blocks, not just page-level discussions. Defaults to false." }, "discussion_id": { "type": "string", "description": "Fetch a specific discussion by ID or discussion URL (e.g., discussion://pageId/blockId/discussionId)." } }, "required": ["page_id"], "description": "The parameters for the get_comments tool. Get comments and discussions from a Notion page.\n\nReturns discussions with full comment content in XML format.\nBy default, returns page-level discussions only.\n\nTip: Use the `fetch` tool with `include_discussions: true` first to see where discussions\nare anchored in the page content, then use this tool to retrieve full discussion threads.\nThe `discussion://` URLs in the fetch output match the discussion IDs returned here.\n\nParameters:\n- `include_all_blocks`: Include discussions on child blocks (default: false)\n- `include_resolved`: Include resolved discussions (default: false)\n- `discussion_id`: Fetch a specific discussion by ID or URL\n\n{\"page_id\": \"page-uuid\"}\n{\"page_id\": \"page-uuid\", \"include_all_blocks\": true}\n{\"page_id\": \"page-uuid\", \"discussion_id\": \"discussion://pageId/blockId/discussionId\"}" } }, "required": ["type", "get_comments"], "title": "Get Comments" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_async_task", "description": "The name of the tool to run." }, "get_async_task": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1, "examples": ["task_abc123"], "description": "The ID of the async task to retrieve, as returned in the async_task response of the tool that started it." } }, "required": ["task_id"], "description": "The parameters for the get_async_task tool. Retrieves the current status of an async task that was started by another tool\n(for example, \"create_pages\" called with \"allow_async\": true).\n\nThe status is one of \"queued\", \"running\", \"retrying\", \"succeeded\", or \"failed\".\nWhen the task has succeeded, the operation's result is included; when it has\nfailed, an error is included instead.\n\nPoll this tool with the \"task_id\" from the original tool's \"async_task\" response.\nWait briefly between polls — the original response includes a suggested backoff.\n\n\n1. Check a task's status: {\"task_id\": \"task_abc123\"}\n" } }, "required": ["type", "get_async_task"], "title": "Get Async Task" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_teams", "description": "The name of the tool to run." }, "get_teams": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional search query to filter teams by name (case-insensitive)." } }, "description": "The parameters for the get_teams tool. Retrieves a list of teams (teamspaces) in the current workspace. Shows which teams\nexist, user membership status, IDs, names, and roles.\n\nTeams are returned split by membership status and limited to a maximum of\n10 results.\n\n\n1. List all teams (up to the limit of each type): {}\n\n2. Search for teams by name: {\"query\": \"engineering\"}\n\n3. Find a specific team: {\"query\": \"Product Design\"}\n" } }, "required": ["type", "get_teams"], "title": "Get Teams" }, { "type": "object", "properties": { "type": { "type": "string", "const": "get_users", "description": "The name of the tool to run." }, "get_users": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional search query to filter users by name or email (case-insensitive)." }, "start_cursor": { "type": "string", "minLength": 1, "description": "Cursor for pagination. Use the next_cursor value from the previous response to get the next page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of users to return per page (default: 100, max: 100)." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Return only the user matching this ID. Pass \"self\" to fetch the current user." } }, "description": "The parameters for the get_users tool. Retrieves a list of users in the current workspace. Shows workspace members\nand guests with their IDs, names, emails (if available), and types (person or bot).\n\nSupports cursor-based pagination to iterate through all users in the workspace.\n\n\n1. List all users (first page): {}\n\n2. Search for users by name or email: {\"query\": \"john\"}\n\n3. Get next page of results: {\"start_cursor\": \"abc123\"}\n\n4. Set custom page size: {\"page_size\": 20}\n\n5. Fetch a specific user by ID: {\"user_id\": \"00000000-0000-4000-8000-000000000000\"}\n\n6. Fetch the current user: {\"user_id\": \"self\"}\n" } }, "required": ["type", "get_users"], "title": "Get Users" }, { "type": "object", "properties": { "type": { "type": "string", "const": "reply_to_slack_thread", "description": "The name of the tool to run." }, "reply_to_slack_thread": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The Slack message to post as a reply in the triggering thread. Use Slack markdown formatting." }, "unfurl_links": { "type": "boolean", "description": "Whether Slack should unfurl links in the reply. Defaults to true." } }, "required": ["message"], "description": "The parameters for the reply_to_slack_thread tool. Reply to the Slack thread that triggered the current workflow run.\n\nThis tool is only available to external agent harnesses running from a Slack-triggered\nworkflow with an active Slack connection. It cannot reply to arbitrary Slack channels\nor threads; the destination is fixed to the triggering thread for this workflow run.\nUse Slack markdown formatting in message text." } }, "required": ["type", "reply_to_slack_thread"], "title": "Reply To Slack Thread" }, { "type": "object", "properties": { "type": { "type": "string", "const": "answer_question", "description": "The name of the tool to run." }, "answer_question": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Question to answer using content from the user's Notion workspace." } }, "required": ["question"], "description": "The parameters for the answer_question tool. Get a single AI-generated answer to a question using content from the user's\nNotion workspace. This tool does not search connected sources such as Slack,\nGoogle Drive, or GitHub. Returns one concise answer, not a list of results.\n\nUse this when you want a direct answer and don't need to read the underlying\npages yourself. It's faster and far cheaper on tokens than fetching many search\nresults and synthesizing them yourself.\n\nUse search instead if you want a ranked list of results to read, filter, or fetch\nin full, or if you need precise control over which sources inform the answer. If\nan answer isn't enough for the task, fall back to search to retrieve and read the\nfull results.\n\nFree during beta." } }, "required": ["type", "answer_question"], "title": "Answer Question" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_data_sources", "description": "The name of the tool to run." }, "query_data_sources": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "data_source_urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Notion data source URLs whose SQLite tables are available to the query;\neach data source is exposed as a table named by its URL. Obtain them from the\nfetch tool, in the format: collection://f336d0bc-b841-465b-8045-024475c079dd" }, "query": { "type": "string", "description": "Read-only SQLite query to execute against the data sources. Use a data\nsource URL as the table name, e.g. SELECT * FROM \"collection://...\" WHERE ....\nInclude every needed filter in WHERE (filters on views of the data source are\nnot automatically applied). For time comparisons or ordering, normalize text\ntimestamps with datetime(...) or date(...)." }, "mode": { "type": "string", "const": "sql", "description": "Optional mode parameter. Defaults to 'sql' if not specified." }, "params": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "maxItems": 100, "description": "Positional parameters bound to `?` placeholders in the query. Prefer\nparameterized queries over string interpolation. Use \"__YES__\" for checked\ncheckboxes and \"__NO__\" for unchecked checkboxes." } }, "additionalProperties": false, "required": ["data_source_urls", "query"], "title": "Sql" }, { "type": "object", "properties": { "mode": { "type": "string", "const": "view", "description": "Mode for executing a database view's existing query" }, "view_url": { "type": "string", "description": "URL of a specific database view to query.\nExample: https://www.notion.so/workspace/db-id?v=view-id" }, "start_cursor": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Cursor for pagination. Use the next_cursor value from the previous response to get the next page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of rows to return per page (default: 100, max: 100)." }, "is_archived": { "type": "boolean", "description": "Optional archive selector. Omitted or false queries non-archived rows only; true queries archived rows only." } }, "additionalProperties": false, "required": ["mode", "view_url"], "title": "View" } ], "description": "The data required for querying data sources" } }, "required": ["data"], "description": "The parameters for the query_data_sources tool. Query data from Notion databases using SQL or by specifying a view. This is the canonical replacement for the deprecated query_database_view tool.\n\nBy default, uses SQL mode to execute SQLite queries against one or more data sources.\nAlternatively, use view mode to execute a database view's existing filters and sorts. Pass the same view_url previously used with query_database_view.\nArchive selection is supported in view mode only. SQL mode does not accept\n\"is_archived\"; SQL archive support is a separate infrastructure follow-up.\n\nLimits: View mode is available without a tool-specific quota on every plan.\nSQL is unlimited on Business and Enterprise plans with Notion AI. Other plans\nhave a shared workspace usage limit for single-data-source queries and cannot\nquery multiple data sources at once.\n\nPrerequisites:\n1. Use the \"fetch\" tool first to get database schema and data source URLs\n2. Data source URLs are found in tags in fetch results\n\nSQL mode (default):\nExecute custom SQLite queries against one or more data sources.\n- Use data source URLs as table names in your query\n- Supports parameterized queries for security\n- Checkbox values: use \"__YES__\" for checked, \"__NO__\" for unchecked\n\nExamples:\n1. Simple query without explicit mode (defaults to SQL):\n{\n \"data\": {\n \"data_source_urls\": [\"collection://f336d0bc-b841-465b-8045-024475c079dd\"],\n \"query\": \"SELECT * FROM \\\"collection://f336d0bc-b841-465b-8045-024475c079dd\\\" LIMIT 10\"\n }\n}\n\n2. Query with parameters:\n{\n \"data\": {\n \"mode\": \"sql\",\n \"data_source_urls\": [\"collection://abc123\"],\n \"query\": \"SELECT * FROM \\\"collection://abc123\\\" WHERE Status = ? AND Priority = ?\",\n \"params\": [\"In Progress\", \"High\"]\n }\n}\n\n3. Query checkboxes:\n{\n \"data\": {\n \"data_source_urls\": [\"collection://def456\"],\n \"query\": \"SELECT * FROM \\\"collection://def456\\\" WHERE Completed = ?\",\n \"params\": [\"__YES__\"]\n }\n}\n\nView mode:\nExecute a specific database view's query with its filters and sorts.\nOmit \"is_archived\" or set it to false for non-archived rows. Set\n\"is_archived\": true to apply the view inside the archived partition.\nWhen the response has \"has_more\": true, pass its \"next_cursor\" as\n\"start_cursor\" in a follow-up view-mode request with the same \"is_archived\"\nvalue.\n\nExample:\n{\n \"data\": {\n \"mode\": \"view\",\n \"view_url\": \"https://www.notion.so/workspace/Tasks-DB-abc123?v=def456\",\n \"is_archived\": false\n }\n}\n\nCommon use cases:\n- Aggregate data across databases\n- Filter records by complex conditions\n- Export data for analysis\n- Validate data quality\n- Generate reports from database content" } }, "required": ["type", "query_data_sources"], "title": "Query Data Sources" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_multiple_data_sources", "description": "The name of the tool to run." }, "query_multiple_data_sources": { "type": "object", "properties": { "query": { "type": "string", "description": "Read-only SQLite query to execute against the data sources. Use a data\nsource URL as the table name, e.g. SELECT * FROM \"collection://...\" WHERE ....\nInclude every needed filter in WHERE (filters on views of the data source are\nnot automatically applied). For time comparisons or ordering, normalize text\ntimestamps with datetime(...) or date(...)." }, "data_source_urls": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 2, "description": "Notion data source URLs whose SQLite tables are available to the query;\neach data source is exposed as a table named by its URL. Obtain them from the\nfetch tool, in the format: collection://f336d0bc-b841-465b-8045-024475c079dd" }, "params": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "maxItems": 100, "description": "Positional parameters bound to `?` placeholders in the query. Prefer\nparameterized queries over string interpolation. Use \"__YES__\" for checked\ncheckboxes and \"__NO__\" for unchecked checkboxes." }, "mode": { "type": "string", "const": "sql", "description": "Optional SQL mode marker. This tool only supports SQL queries." } }, "additionalProperties": false, "required": ["query", "data_source_urls"], "description": "The parameters for the query_multiple_data_sources tool. Query data across multiple Notion data sources using read-only SQLite SQL.\n\nUse this tool for JOINs, UNIONs, comparisons, and aggregations that need two or more data sources. Queries across multiple data sources require a Business or Enterprise plan with Notion AI. Use query_data_sources instead when you need one data source or a saved database view.\n\nPrerequisites:\n1. Use the \"fetch\" tool first to get each data source's schema and collection:// URL.\n2. Data source URLs are found in tags in fetch results.\n\nSQL:\n- Use each collection:// URL as a quoted SQLite table name in the query.\n- Bind untrusted values with ? placeholders and params; do not interpolate them into SQL.\n- Include every needed filter in WHERE. Saved-view filters and sorts are not automatically applied.\n- Checkbox values: use \"__YES__\" for checked and \"__NO__\" for unchecked.\n\nReturns matching rows, the queried data source IDs, and whether results were truncated." } }, "required": ["type", "query_multiple_data_sources"], "title": "Query Multiple Data Sources" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_database_view", "description": "The name of the tool to run." }, "query_database_view": { "type": "object", "properties": { "view_url": { "type": "string", "description": "URL of a specific database view to query.\nExample: https://www.notion.so/workspace/db-id?v=view-id" }, "start_cursor": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Cursor for pagination. Use the next_cursor value from the previous response to get the next page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of rows to return per page (default: 100, max: 100)." }, "is_archived": { "type": "boolean", "description": "Optional archive selector. Omitted or false queries non-archived rows only; true queries archived rows only." } }, "required": ["view_url"], "description": "The parameters for the query_database_view tool. [DEPRECATED] Use query_data_sources with mode: \"view\" and the same view_url instead. This tool will be removed in a future release.\n\nQuery data from a Notion database view.\n\nExecutes a database view's existing filters, sorts, and column selections to return matching pages.\nUse this to query a view exactly as configured. For custom SQL queries, aggregation, or querying across multiple data sources, use query_data_sources instead.\nBy default, it returns non-archived rows only. Set \"is_archived\": true to query archived rows only.\n\nPrerequisites:\n1. Use the \"fetch\" tool first to get the database and its view URLs\n2. View URLs are found in database responses, typically in the format:\n https://www.notion.so/workspace/db-id?v=view-id\n\nExample:\n{\n \"view_url\": \"https://www.notion.so/workspace/Tasks-DB-abc123?v=def456\",\n \"is_archived\": false\n}\n\nWhen the response has \"has_more\": true, pass its \"next_cursor\" as\n\"start_cursor\" in a follow-up request with the same \"is_archived\" value.\n\nCommon use cases:\n- Query databases using pre-defined views (filters/sorts already configured), e.g. look for all tickets marked \"In Progress\" in a Tasks DB\n- Export filtered data for analysis\n- Generate reports from database content" } }, "required": ["type", "query_database_view"], "title": "Query Database View" }, { "type": "object", "properties": { "type": { "type": "string", "const": "query_meeting_notes", "description": "The name of the tool to run." }, "query_meeting_notes": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "operator": { "type": "string", "enum": ["and", "or"], "description": "Operator for combinator filters." }, "filters": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "property": { "type": "string", "enum": [ "title", "attendees", "created_time", "created_by", "last_edited_time", "last_edited_by", "notion://meeting_notes/attendees" ], "description": "Which meeting-note property to filter on. Prefer the short names; the schema URI form is accepted for compatibility." }, "filter": { "oneOf": [ { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "string_is", "string_is_not", "string_contains", "string_does_not_contain", "string_starts_with", "string_ends_with" ], "description": "How to compare the text." }, "value": { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "string", "description": "The literal text the operator compares against." } }, "additionalProperties": false, "required": [ "type", "value" ], "description": "The text to compare against." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "person_contains", "person_does_not_contain" ], "description": "Whether the property must contain the people listed." }, "value": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "object", "properties": { "table": { "type": "string", "const": "notion_user", "description": "Always `notion_user`" }, "id": { "type": "string", "examples": [ "3f2b25f3-0a52-4a90-8f0d-5a3f0e6c1d2e", "user://3f2b25f3-0a52-4a90-8f0d-5a3f0e6c1d2e" ], "description": "The user's ID, as a UUID or the `user://` form returned by user search." } }, "additionalProperties": false, "required": [ "table", "id" ], "description": "Pointer to the Notion user to match." } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "me", "description": "Always `me`" } }, "additionalProperties": false, "required": [ "type", "value" ] } ] }, "maxItems": 100, "description": "The people to compare against." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "date_is", "date_is_before", "date_is_after", "date_is_on_or_before", "date_is_on_or_after" ], "description": "How to compare the date." }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "enum": [ "today", "tomorrow", "yesterday", "one_week_ago", "one_week_from_now", "one_month_ago", "one_month_from_now" ], "description": "One of: `today`, `tomorrow`, `yesterday`, `one_week_ago`, `one_week_from_now`, `one_month_ago`, `one_month_from_now`" } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "The calendar date as an ISO 8601 date string." } }, "additionalProperties": false, "required": [ "type", "start_date" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "datetime", "description": "Always `datetime`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "The calendar date as an ISO 8601 date string." }, "start_time": { "type": "string", "examples": [ "09:30" ], "description": "The time of day in 24-hour HH:MM format." }, "time_zone": { "type": "string", "examples": [ "America/Los_Angeles" ], "description": "The IANA time zone name the time is interpreted in." } }, "additionalProperties": false, "required": [ "type", "start_date", "start_time", "time_zone" ] } ], "description": "Use the is_empty operator to match an unset date." } }, "additionalProperties": false, "required": [ "type", "value" ] } ], "description": "The date to compare against." }, "use_end": { "type": "boolean", "description": "Compare against the end of a date range rather than its start." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "date_is_within", "date_is_relative_to" ], "description": "How to compare the date against the range." }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "custom", "description": "Always `custom`" }, "direction": { "type": "string", "enum": [ "past", "future" ], "description": "Whether the window runs backwards or forwards from now." }, "unit": { "type": "string", "enum": [ "year", "month", "week", "day" ], "description": "One of: `year`, `month`, `week`, `day`" }, "count": { "type": "integer", "minimum": 1, "description": "How many units wide the window is." } }, "additionalProperties": false, "required": [ "type", "value", "direction", "unit", "count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "surrounding", "description": "Always `surrounding`" }, "unit": { "type": "string", "enum": [ "year", "month", "week", "day" ], "description": "One of: `year`, `month`, `week`, `day`" } }, "additionalProperties": false, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "enum": [ "this_week", "the_past_week", "the_past_month", "the_past_year", "the_next_week", "the_next_month", "the_next_year" ], "description": "One of: `this_week`, `the_past_week`, `the_past_month`, `the_past_year`, `the_next_week`, `the_next_month`, `the_next_year`" } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "object", "properties": { "type": { "type": "string", "const": "daterange", "description": "Always `daterange`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "Inclusive start of the range as an ISO 8601 date string, if any." }, "end_date": { "type": "string", "examples": [ "1991-01-04" ], "format": "date", "description": "Inclusive end of the range as an ISO 8601 date string, if any." } }, "additionalProperties": false, "required": [ "type" ], "description": "Use the is_empty operator to match an unset date." } }, "additionalProperties": false, "required": [ "type", "value" ] } ], "description": "The range to compare against." }, "use_end": { "type": "boolean", "description": "Compare against the end of a date range rather than its start." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Whether the property must be empty or set." } }, "additionalProperties": false, "required": ["operator"] } ], "description": "The comparison to apply. Use the arm matching the property's type." } }, "additionalProperties": false, "required": ["property", "filter"] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": ["and", "or"], "description": "Whether every child must match, or any of them." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string", "enum": [ "title", "attendees", "created_time", "created_by", "last_edited_time", "last_edited_by", "notion://meeting_notes/attendees" ], "description": "Which meeting-note property to filter on. Prefer the short names; the schema URI form is accepted for compatibility." }, "filter": { "oneOf": [ { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "string_is", "string_is_not", "string_contains", "string_does_not_contain", "string_starts_with", "string_ends_with" ], "description": "How to compare the text." }, "value": { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "string", "description": "The literal text the operator compares against." } }, "additionalProperties": false, "required": [ "type", "value" ], "description": "The text to compare against." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "person_contains", "person_does_not_contain" ], "description": "Whether the property must contain the people listed." }, "value": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "object", "properties": { "table": { "type": "string", "const": "notion_user", "description": "Always `notion_user`" }, "id": { "type": "string", "examples": [ "3f2b25f3-0a52-4a90-8f0d-5a3f0e6c1d2e", "user://3f2b25f3-0a52-4a90-8f0d-5a3f0e6c1d2e" ], "description": "The user's ID, as a UUID or the `user://` form returned by user search." } }, "additionalProperties": false, "required": [ "table", "id" ], "description": "Pointer to the Notion user to match." } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "me", "description": "Always `me`" } }, "additionalProperties": false, "required": [ "type", "value" ] } ] }, "maxItems": 100, "description": "The people to compare against." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "date_is", "date_is_before", "date_is_after", "date_is_on_or_before", "date_is_on_or_after" ], "description": "How to compare the date." }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "enum": [ "today", "tomorrow", "yesterday", "one_week_ago", "one_week_from_now", "one_month_ago", "one_month_from_now" ], "description": "One of: `today`, `tomorrow`, `yesterday`, `one_week_ago`, `one_week_from_now`, `one_month_ago`, `one_month_from_now`" } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "date", "description": "Always `date`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "The calendar date as an ISO 8601 date string." } }, "additionalProperties": false, "required": [ "type", "start_date" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "datetime", "description": "Always `datetime`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "The calendar date as an ISO 8601 date string." }, "start_time": { "type": "string", "examples": [ "09:30" ], "description": "The time of day in 24-hour HH:MM format." }, "time_zone": { "type": "string", "examples": [ "America/Los_Angeles" ], "description": "The IANA time zone name the time is interpreted in." } }, "additionalProperties": false, "required": [ "type", "start_date", "start_time", "time_zone" ] } ], "description": "Use the is_empty operator to match an unset date." } }, "additionalProperties": false, "required": [ "type", "value" ] } ], "description": "The date to compare against." }, "use_end": { "type": "boolean", "description": "Compare against the end of a date range rather than its start." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "date_is_within", "date_is_relative_to" ], "description": "How to compare the date against the range." }, "value": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "custom", "description": "Always `custom`" }, "direction": { "type": "string", "enum": [ "past", "future" ], "description": "Whether the window runs backwards or forwards from now." }, "unit": { "type": "string", "enum": [ "year", "month", "week", "day" ], "description": "One of: `year`, `month`, `week`, `day`" }, "count": { "type": "integer", "minimum": 1, "description": "How many units wide the window is." } }, "additionalProperties": false, "required": [ "type", "value", "direction", "unit", "count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "const": "surrounding", "description": "Always `surrounding`" }, "unit": { "type": "string", "enum": [ "year", "month", "week", "day" ], "description": "One of: `year`, `month`, `week`, `day`" } }, "additionalProperties": false, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "relative", "description": "Always `relative`" }, "value": { "type": "string", "enum": [ "this_week", "the_past_week", "the_past_month", "the_past_year", "the_next_week", "the_next_month", "the_next_year" ], "description": "One of: `this_week`, `the_past_week`, `the_past_month`, `the_past_year`, `the_next_week`, `the_next_month`, `the_next_year`" } }, "additionalProperties": false, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "exact", "description": "Always `exact`" }, "value": { "type": "object", "properties": { "type": { "type": "string", "const": "daterange", "description": "Always `daterange`" }, "start_date": { "type": "string", "examples": [ "1990-12-28" ], "format": "date", "description": "Inclusive start of the range as an ISO 8601 date string, if any." }, "end_date": { "type": "string", "examples": [ "1991-01-04" ], "format": "date", "description": "Inclusive end of the range as an ISO 8601 date string, if any." } }, "additionalProperties": false, "required": [ "type" ], "description": "Use the is_empty operator to match an unset date." } }, "additionalProperties": false, "required": [ "type", "value" ] } ], "description": "The range to compare against." }, "use_end": { "type": "boolean", "description": "Compare against the end of a date range rather than its start." } }, "additionalProperties": false, "required": [ "operator", "value" ] }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "is_empty", "is_not_empty" ], "description": "Whether the property must be empty or set." } }, "additionalProperties": false, "required": ["operator"] } ], "description": "The comparison to apply. Use the arm matching the property's type." } }, "additionalProperties": false, "required": [ "property", "filter" ] }, "maxItems": 100, "description": "The conditions in this group. A group with no conditions matches nothing, so send at least one." } }, "additionalProperties": false, "required": ["operator", "filters"] } ] }, "maxItems": 100, "description": "Nested filters; each may be a combinator (and/or) or property filter." } }, "required": ["operator"], "description": "Acceptable filter for querying current user's meeting notes data source." } }, "description": "The parameters for the query_meeting_notes tool. Query the current user's meeting notes data source.\n\nApplies a filter over meeting note properties. Title keyword searching is done via filter on property \"title\" (e.g. string_contains).\nTitle keyword matching is case-insensitive; capitalization does not matter.\nReturns up to 50 rows of matching meeting notes.\n\nPrerequisites:\n1. Use the \"search\" tool to find people IDs if you need to filter by attendees\n\nQuery building:\n- Ignore terms semantically related to meeting outputs (e.g. \"summaries\", \"notes\", \"todos\", \"action items\", \"deliverables\"). These signal the user wants outcomes from their meetings, not a title filter.\n- For example, \"what are my meeting todos?\" means filter meetings and find action items — do NOT add a title filter for \"todos\".\n- Only add a title filter when confident the user is targeting a specific meeting title (e.g. \"standup\", \"sprint planning\", \"1:1 with Alice\").\n- Generic date phrases like \"recent meetings\", \"latest meetings\", \"meetings this week\", or \"yesterday's meetings\" should be interpreted as date range filters — never as title filters.\n- If a filter returns no results, simplify to a single term. The system is lexical, so multi-word title filters may not match.\n- Unless a user explicitly asks about a meeting titled with another user's name, assume they're referring to attendees or creators. Only add a title filter with a person's name as a fallback if attendee filtering returns no results.\n\nDefault behavior:\n- This tool by default returns meeting notes where the current user is an attendee or creator. There is no need to add a filter for the current user.\n\nFilterable properties:\n- \"title\" (text) — meeting title\n- \"attendees\" (person) — meeting attendees\n- \"created_time\" (date) — when the meeting note was created\n- \"created_by\" (person) — who created the meeting note\n- \"last_edited_time\" (date) — when the meeting note was last edited\n- \"last_edited_by\" (person) — who last edited the meeting note\n\nCombinator filters use \"filters\" (not \"operands\"):\n{\n \"operator\": \"and\" | \"or\",\n \"filters\": [ ... ]\n}\n\nDate filtering (recommended default: date_is_within):\n- Prefer \"date_is_within\" for relative windows like \"past N days/weeks/months\".\n- Relative (common): { type: \"relative\", value: \"the_past_week\" | \"the_past_month\" | \"this_week\" }\n- Relative (custom): { type: \"relative\", value: \"custom\", direction: \"past\" | \"future\", unit: \"day\" | \"week\" | \"month\" | \"year\", count: }\n- Exact range: { type: \"exact\", value: { type: \"daterange\", start_date: \"YYYY-MM-DD\", end_date: \"YYYY-MM-DD\" } }\n- Single-date operators (\"date_is\", \"date_is_before\", \"date_is_after\", \"date_is_on_or_before\", \"date_is_on_or_after\"):\n - Exact: { type: \"exact\", value: { type: \"date\", start_date: \"YYYY-MM-DD\" } }\n - Relative shortcuts: today | tomorrow | yesterday | one_week_ago | one_week_from_now | one_month_ago | one_month_from_now\n\nTitle keyword filtering (OR vs AND):\n- Use OR (\"operator\": \"or\") when unsure or for broad discovery.\n- Use AND (\"operator\": \"and\") when the user is specific and you want to narrow results.\n- Break multi-word phrases into individual terms and filter on each term separately.\n\nExample 1: Filter meetings from the past week (relative):\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_within\",\n \"value\": { \"type\": \"relative\", \"value\": \"the_past_week\" }\n }\n }\n ]\n }\n}\n\nExample 2: Filter meetings from the past 3 days (custom relative):\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_within\",\n \"value\": { \"type\": \"relative\", \"value\": \"custom\", \"direction\": \"past\", \"unit\": \"day\", \"count\": 3 }\n }\n }\n ]\n }\n}\n\nExample 3: Filter meetings by exact date range:\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_within\",\n \"value\": { \"type\": \"exact\", \"value\": { \"type\": \"daterange\", \"start_date\": \"2025-01-01\", \"end_date\": \"2025-12-31\" } }\n }\n }\n ]\n }\n}\n\nExample 4: Filter meetings created after a specific date:\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_after\",\n \"value\": { \"type\": \"exact\", \"value\": { \"type\": \"date\", \"start_date\": \"2025-06-01\" } }\n }\n }\n ]\n }\n}\n\nExample 5: Filter meetings by a specific attendee (use \"search\" tool first to get user ID):\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"attendees\",\n \"filter\": {\n \"operator\": \"person_contains\",\n \"value\": [\n { \"type\": \"exact\", \"value\": { \"table\": \"notion_user\", \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\" } }\n ]\n }\n }\n ]\n }\n}\n\nExample 6: Combine attendees with date range:\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_on_or_after\",\n \"value\": { \"type\": \"exact\", \"value\": { \"type\": \"date\", \"start_date\": \"2025-01-01\" } }\n }\n },\n {\n \"property\": \"created_time\",\n \"filter\": {\n \"operator\": \"date_is_on_or_before\",\n \"value\": { \"type\": \"exact\", \"value\": { \"type\": \"date\", \"start_date\": \"2025-01-31\" } }\n }\n },\n {\n \"property\": \"attendees\",\n \"filter\": {\n \"operator\": \"person_contains\",\n \"value\": [\n { \"type\": \"exact\", \"value\": { \"table\": \"notion_user\", \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\" } }\n ]\n }\n }\n ]\n }\n}\n\nExample 7: Filter meetings by title content:\n{\n \"filter\": {\n \"operator\": \"and\",\n \"filters\": [\n {\n \"property\": \"title\",\n \"filter\": {\n \"operator\": \"string_contains\",\n \"value\": { \"type\": \"exact\", \"value\": \"design review\" }\n }\n }\n ]\n }\n}\n\nExample 8: Filter meetings matching any of several title terms (using \"or\"):\n{\n \"filter\": {\n \"operator\": \"or\",\n \"filters\": [\n {\n \"property\": \"title\",\n \"filter\": {\n \"operator\": \"string_contains\",\n \"value\": { \"type\": \"exact\", \"value\": \"standup\" }\n }\n },\n {\n \"property\": \"title\",\n \"filter\": {\n \"operator\": \"string_contains\",\n \"value\": { \"type\": \"exact\", \"value\": \"sync\" }\n }\n }\n ]\n }\n}" } }, "required": ["type", "query_meeting_notes"], "title": "Query Meeting Notes" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_agents", "description": "The name of the tool to run." }, "list_agents": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional search query to filter agents by name or description (case-insensitive)." }, "start_cursor": { "type": "string", "minLength": 1, "description": "Cursor for pagination. Use the next_cursor value from the previous response to get the next page." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of agents to return per page (default: 50, max: 100)." } }, "description": "The parameters for the list_agents tool. Retrieves a list of all custom agents (workflows) that the authenticated user has access to in the current workspace.\nThis tool provides visibility into available agents including their names, IDs, descriptions, and system instructions.\n\nThe optional query filters agents by case-insensitive substring match on their name and description. Results are\npaginated: when has_more is true, pass the response's next_cursor back as start_cursor to fetch the next page.\n\nThe returned data includes:\n- Agent ID\n- Agent name\n- Agent description\n- Agent system instructions\n\n\n1. List all available agents: {}\n\n2. Filter agents by name or description: {\"query\": \"customer support\"}\n\n3. Get next page of results: {\"start_cursor\": \"...\"}\n\n4. Set custom page size: {\"page_size\": 20}\n" } }, "required": ["type", "list_agents"], "title": "List Agents" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_private_pages", "description": "The name of the tool to run." }, "list_private_pages": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "description": "The parameters for the list_private_pages tool. List the current user's top-level pages and databases in their Private sidebar section. Use this to browse private workspace structure; use search when looking for content by meaning or keyword. Follow cursor pagination when the complete list is needed." } }, "required": ["type", "list_private_pages"], "title": "List Private Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_shared_pages", "description": "The name of the tool to run." }, "list_shared_pages": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "description": "The parameters for the list_shared_pages tool. List pages and databases in the current user's Shared sidebar section. Use this to browse content shared directly with the user; use search when looking for content by meaning or keyword. Follow cursor pagination when the complete list is needed." } }, "required": ["type", "list_shared_pages"], "title": "List Shared Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_favorite_pages", "description": "The name of the tool to run." }, "list_favorite_pages": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "description": "The parameters for the list_favorite_pages tool. List the current user's favorite pages and databases in sidebar order. Use this when the user refers to a favorite or pinned workspace item. Follow cursor pagination when the complete list is needed." } }, "required": ["type", "list_favorite_pages"], "title": "List Favorite Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "list_recent_pages", "description": "The name of the tool to run." }, "list_recent_pages": { "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "description": "The parameters for the list_recent_pages tool. List pages and databases the current user recently viewed, ranked by recency and visit frequency. Use this to recover likely navigation context when the user refers to something they were recently working on. Follow cursor pagination when the complete list is needed." } }, "required": ["type", "list_recent_pages"], "title": "List Recent Pages" }, { "type": "object", "properties": { "type": { "type": "string", "const": "search_agents", "description": "The name of the tool to run." }, "search_agents": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["favorites", "workspace"], "description": "Which agents to list: \"favorites\" for the current user's favorite agents, or \"workspace\" for agents shared with the workspace." }, "query": { "type": "string", "description": "Search text matched against agent names and descriptions. When omitted, favorites are returned in sidebar order and workspace agents are returned newest first." }, "limit": { "type": "number", "description": "Maximum results to return (1-200)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from the previous response." } }, "additionalProperties": false, "required": ["scope"], "description": "The parameters for the search_agents tool. Search agents by name or description, or browse the current user's favorite agents and the workspace's newest agents. Use this instead of list_agents when personal favorites or relevance-ranked search are needed." } }, "required": ["type", "search_agents"], "title": "Search Agents" }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_view", "description": "The name of the tool to run." }, "create_view": { "type": "object", "properties": { "data_source_id": { "type": "string", "description": "The data source (collection) ID. Accepts a collection:// URI from tags or a bare UUID." }, "name": { "type": "string", "description": "The name of the view." }, "type": { "type": "string", "enum": [ "table", "board", "list", "calendar", "timeline", "gallery", "form", "chart", "map", "dashboard" ], "description": "The type of view to create." }, "database_id": { "type": "string", "description": "The database to add a view tab to. Accepts a Notion URL or a bare UUID. Mutually exclusive with `parent_page_id`; exactly one must be provided." }, "parent_page_id": { "type": "string", "description": "A page to create an inline linked database view on. Accepts a Notion URL or a bare UUID. The new linked view block is appended at the end of the page and references `data_source_id`. Mutually exclusive with `database_id`; exactly one must be provided." }, "configure": { "type": "string", "description": "View configuration DSL string. Supports FILTER, SORT BY, GROUP BY, CALENDAR BY, TIMELINE BY, MAP BY, CHART, FORM, SHOW, HIDE, COVER, WRAP CELLS, and FREEZE COLUMNS directives. See notion://docs/view-dsl-spec." } }, "required": ["data_source_id", "name", "type"], "description": "The parameters for the create_view tool. Create a new view on a Notion database.\n\nExactly one of \"database_id\" or \"parent_page_id\" must be provided:\n- \"database_id\": add a new view tab to an existing database.\n- \"parent_page_id\": create an inline linked database view on a page that\n references the existing \"data_source_id\" (like the UI \"/linked\" command).\n The linked view block is appended to the end of the parent page.\n\nUse \"fetch\" first to get the database_id, parent_page_id, and data_source_id\n(from tags in the response). The caller must have edit access\nto the database (or parent page) and access to the data source.\n\nSupported types: table, board, list, calendar, timeline, gallery, form, chart, map, dashboard.\n\nThe optional \"configure\" param accepts a DSL for filters, sorts, grouping,\nand display options. See the notion://docs/view-dsl-spec resource for full\nsyntax (readable via your MCP client's resource-reading interface, or by\npassing the URI to the Notion \"fetch\" tool). Key directives:\n- FILTER \"Property\" = \"value\" — filter rows. Relation values must be a page\n URL or UUID; person values must be a user URI (user://), user\n UUID, or \"me\". Names are not supported for either.\n- SORT BY \"Property\" ASC — sort rows\n- GROUP BY \"Property\" — group by property (required for board views)\n- CALENDAR BY \"Property\" — date property (required for calendar views)\n- TIMELINE BY \"Start\" TO \"End\" — date range (required for timeline views)\n- MAP BY \"Property\" — location property (required for map views)\n- CHART column|bar|line|donut|number — chart type with optional AGGREGATE, COLOR, HEIGHT, SORT, STACK BY, CAPTION\n- FORM CLOSE|OPEN — close/open form submissions\n- FORM ANONYMOUS true|false — toggle anonymous submissions\n- FORM PERMISSIONS none|reader|editor — set submission permissions\n- SHOW \"Prop1\", \"Prop2\" — set visible properties\n- COVER \"Property\" — cover image property\n\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"All Tasks\", \"type\": \"table\"}\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"Task Board\", \"type\": \"board\", \"configure\": \"GROUP BY \\\"Status\\\"\"}\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"Active\", \"type\": \"table\", \"configure\": \"FILTER \\\"Status\\\" = \\\"In Progress\\\"; SORT BY \\\"Due Date\\\" ASC\"}\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"Calendar\", \"type\": \"calendar\", \"configure\": \"CALENDAR BY \\\"Due Date\\\"\"}\n{\"database_id\": \"abc123\", \"data_source_id\": \"def456\", \"name\": \"Overview\", \"type\": \"dashboard\"}\n{\"parent_page_id\": \"ghi789\", \"data_source_id\": \"def456\", \"name\": \"Company tasks\", \"type\": \"table\", \"configure\": \"FILTER \\\"Company\\\" = \\\"Acme\\\"\"}" } }, "required": ["type", "create_view"], "title": "Create View" }, { "type": "object", "properties": { "type": { "type": "string", "const": "update_view", "description": "The name of the tool to run." }, "update_view": { "type": "object", "properties": { "view_id": { "type": "string", "description": "The view to update. Accepts a view:// URI, a Notion URL with ?v= parameter, or a bare UUID." }, "name": { "type": "string", "description": "New name for the view." }, "configure": { "type": "string", "description": "View configuration DSL string. Supports FILTER, SORT BY, GROUP BY, CALENDAR BY, TIMELINE BY, MAP BY, CHART, FORM, SHOW, HIDE, COVER, WRAP CELLS, FREEZE COLUMNS, and CLEAR directives." } }, "required": ["view_id"], "description": "The parameters for the update_view tool. Update a view's name, filters, sorts, or display configuration.\n\nUse \"fetch\" to get view IDs from database responses. Only include fields\nyou want to change. The \"configure\" param uses the same DSL as create_view.\nUse CLEAR to remove settings:\n- CLEAR FILTER — remove all filters\n- CLEAR SORT — remove all sorts\n- CLEAR GROUP BY — remove grouping\n\nSee notion://docs/view-dsl-spec resource for full syntax (readable via your\nMCP client's resource-reading interface, or by passing the URI to the Notion\n\"fetch\" tool).\n\n{\"view_id\": \"abc123\", \"name\": \"Sprint Board\"}\n{\"view_id\": \"abc123\", \"configure\": \"FILTER \\\"Status\\\" = \\\"Done\\\"\"}\n{\"view_id\": \"abc123\", \"configure\": \"CLEAR FILTER; SORT BY \\\"Created\\\" DESC\"}\n{\"view_id\": \"abc123\", \"configure\": \"GROUP BY \\\"Priority\\\"; SHOW \\\"Name\\\", \\\"Status\\\"\"}" } }, "required": ["type", "update_view"], "title": "Update View" }, { "type": "object", "properties": { "type": { "type": "string", "const": "search_emails", "description": "The name of the tool to run." }, "search_emails": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Search query string using Gmail-style search operators (e.g. from:, is:unread, newer_than:1d, after:/before:, subject:)." }, "user_email_address": { "type": "string", "minLength": 3, "maxLength": 320, "description": "The email address of the mailbox to search. Omit to use the user's default connected account." }, "count": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Number of results to return (default: 20, max: 500)." }, "page_token": { "type": "string", "minLength": 1, "description": "Pagination token from previous search results." }, "include_spam_trash": { "type": "boolean", "description": "Whether to include spam and trash in results. Defaults to false." } }, "required": ["query"], "description": "The parameters for the search_emails tool. Search the user's email inbox (their Notion Mail connected account) using\nGmail query syntax, and return matching threads with ids, participants,\ndates, and snippets.\n\nThis searches the user's personal mailbox, not Notion workspace content —\nuse the regular \"search\" tool for pages and databases. Only Gmail-backed\naccounts are supported by this tool.\n\nQuery guidance: use Gmail-style operators (from:, to:, subject:, is:unread,\nhas:attachment, newer_than:1d, after:/before:). For topic or digest requests,\nprefer recency (newer_than:1d) and/or sender (from:) filters over subject:\nkeyword filtering: subjects don't reliably contain the topic word, and when\nfiltering by subject/body cover synonyms rather than over-filtering one term.\nDate bounds after:/before: take a plain date with no time component\n(before:2026/05/08 or before:2026-05-08); a time component is not valid Gmail\nsyntax and silently returns nothing.\n\nEach result includes a threadId: a single opaque string, possibly with a\nverification stamp appended after a \".\" (e.g. 1894c2bd0f58f2b7.a83f92c1).\nPass the whole value unchanged to view-thread-content.\n\nResults may include url: a direct provider URL for opening the thread. Use it\ndirectly; never construct a provider URL from threadId or message IDs." } }, "required": ["type", "search_emails"], "title": "Search Emails" }, { "type": "object", "properties": { "type": { "type": "string", "const": "view_thread_content", "description": "The name of the tool to run." }, "view_thread_content": { "type": "object", "properties": { "thread_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The thread ID to view (from search-emails). A stamped ref is accepted as-is." }, "user_email_address": { "type": "string", "minLength": 3, "maxLength": 320, "description": "The email address of the mailbox containing the thread. Omit to use the user's default connected account." }, "most_recent_message_only": { "type": "boolean", "description": "If true (the default), returns only the most recent message. Set false to return all messages in the thread." } }, "required": ["thread_id"], "description": "The parameters for the view_thread_content tool. View the content of an email thread from the user's email inbox (their Notion\nMail connected account), including message bodies and attachment metadata.\n\nUse a threadId returned by search-emails. The id is a single opaque string; a\nverification stamp may be appended after a \".\" (e.g. 1894c2bd0f58f2b7.a83f92c1)\nand that stamp is part of the value, not a separate field — pass the whole\nvalue exactly as received.\n\nThread ids are scoped to the mailbox they were found in: if the search ran\nagainst a non-default mailbox (see searched_email_address in the search\nresult), pass that same address as user_email_address here.\n\nThe response may include url: a direct provider URL for opening the thread. Use\nit directly; never construct a provider URL from threadId or message IDs." } }, "required": ["type", "view_thread_content"], "title": "View Thread Content" } ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runToolResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/rollout/unified": { "post": { "summary": "Run a unified rollout", "operationId": "run-unified-rollout", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["harness", "input"], "description": "A unified rollout request. The harness selects the runner; inputType selects native or agentCall input and defaults to native.", "properties": { "async": { "type": "boolean", "description": "Return immediately with a rollout ID. Defaults to false, which waits up to 45 seconds for a terminal result before returning the current rollout status." }, "harness": { "type": "string", "enum": ["inferenceTranscript", "agentService"] }, "inputType": { "type": "string", "enum": ["native", "agentCall"], "description": "Input representation. `native` uses the selected harness's native payload and is the default; `agentCall` uses the shared shorthand." }, "input": { "type": "object", "description": "Exactly one inline or Braintrust source: {json}, {[org], project, dataset, id}, {[org], project, logId}, or {braintrustSlug}. Inline JSON contains the harness-native input; inferenceTranscript also accepts a full Braintrust-style record." }, "actorId": { "type": "string", "format": "uuid", "description": "Workspace member to run as. Required for content-shaped agentCall inputs." }, "execution": { "type": "object", "properties": { "model": { "type": "string" }, "subagentModel": { "type": "string" }, "rawVendorOverride": {}, "reasoningEffort": { "type": "string" }, "toolPolicy": { "type": "string", "enum": ["auto", "readOnly"] }, "harnessOptions": { "type": "object", "description": "Options specific to the selected harness. AgentService supports local-only `evalSession`; inferenceTranscript has its own options.", "properties": { "evalSession": { "type": "boolean", "description": "For local AgentService agentCall requests, execute against isolated eval-session state." } } } } }, "preprocessors": { "type": "array", "items": { "type": "object" } }, "graders": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object" } ] } }, "braintrust": { "oneOf": [ { "type": "object", "required": ["log"], "properties": { "log": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": ["experiment"], "properties": { "experiment": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } ] }, "response": { "type": "object", "properties": { "raw": { "type": "boolean" }, "input": { "type": "boolean", "description": "Include the executed harness-native input. For inferenceTranscript sources, this is the record's input field rather than the full record." }, "operations": { "type": "boolean", "description": "For AgentService eval sessions, include captured record operations in response metadata." } } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "rolloutId": { "type": "string", "description": "Identifier for this rollout. Use it with GET /v1/rollout/:rollout_id when the result is not terminal." }, "status": { "type": "string", "enum": ["waiting", "running", "complete", "failed"], "description": "Current status of the rollout. Rollouts progress through waiting, running, and then complete or failed." }, "result": { "type": "object", "properties": { "output": { "description": "Inference output." }, "input": { "description": "Original rollout input. Omitted unless explicitly requested via `response.input`." }, "scores": { "description": "Grader results as name-to-score mappings." }, "metadata": { "description": "Inference metadata. Includes post-processor results, grader debug info, raw inference capture under `metadata.logging.rawInferences`, and `metadata.traceUrl` after a successful opt-in Braintrust logging flush." } }, "additionalProperties": false, "required": ["output"], "description": "Rollout result loaded from AI logging S3. Present when status is `complete`." }, "error": { "type": "string", "description": "Bounded failure message. Present when status is `failed`, including when the AI logging S3 output payload is no longer readable." } }, "additionalProperties": false, "required": ["rolloutId", "status"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/external_agent_stub/{agent_id}/sessions/{session_id}/messages": { "post": { "summary": "Send external agent stub session message", "operationId": "send-external-agent-stub-session-message", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "33333333-3333-3333-3333-333333333333", "description": "Always `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent backing this external agent session." } }, { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The provider-owned session ID returned when the session was created." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 10000, "description": "Text message to send to the agent." }, "client_message_id": { "type": "string", "maxLength": 200, "description": "Idempotency key for this message submission. Accepted but not yet used for deduplication by the stub." } }, "required": ["message"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "run_id": { "type": "string" } }, "additionalProperties": false, "required": ["accepted"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/external_agent_stub/{agent_id}/sessions/{session_id}/messages/stream": { "post": { "summary": "Send external agent stub session message (streaming)", "operationId": "send-external-agent-stub-session-message-stream", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "33333333-3333-3333-3333-333333333333", "description": "Always `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent backing this external agent session." } }, { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest", "description": "The provider-owned session ID returned when the session was created." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 10000, "description": "Text message to send to the agent." }, "client_message_id": { "type": "string", "maxLength": 200, "description": "Idempotency key for this message submission. Accepted but not yet used for deduplication by the stub." } }, "required": ["message"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" } }, "required": ["type"], "description": "Schema of a single stream chunk object. The actual response is an NDJSON stream of these objects." } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON) stream. Each line is a JSON-encoded chunk object." } } } } } } }, "/v1/external_agent_stub/{agent_id}/sessions": { "post": { "summary": "Start external agent stub session", "operationId": "start-external-agent-stub-session", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "const": "33333333-3333-3333-3333-333333333333", "description": "Always `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the agent backing this external agent session." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec_version": { "type": "string", "const": "v1", "description": "External Agent API wire version." }, "client_reference_id": { "type": "string", "maxLength": 200, "description": "Idempotency key for one session-creation intent." }, "configs": { "type": "object", "properties": { "mcp_servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "MCP server name." }, "server_url": { "type": "string", "maxLength": 2000, "description": "MCP server URL." }, "credential": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "vault", "description": "Vault-backed credential reference." }, "vault_id": { "type": "string", "maxLength": 200, "description": "Provider-owned vault ID." } }, "required": ["type", "vault_id"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "none", "description": "No authorization credential." } }, "required": ["type"] } ], "description": "Credential vault reference or deliberate no-auth." } }, "required": ["name", "server_url", "credential"] }, "maxItems": 50, "minItems": 1, "description": "The ordered MCP server configuration." } }, "required": ["mcp_servers"], "description": "Vault-backed session configuration." }, "model": { "type": "string", "maxLength": 200, "description": "Preferred model hint. The stub echoes it back and may ignore it." }, "cwd": { "type": "string", "maxLength": 1000, "description": "Working directory hint. Not applicable to this provider; echoed back." }, "locale": { "type": "string", "maxLength": 50, "description": "BCP 47 locale identifier such as `en-US`." }, "system_prompt": { "type": "string", "maxLength": 100000, "description": "Session-scoped instructions for the external agent." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "model": { "type": "string" }, "cwd": { "type": "string" }, "last_active_at": { "type": "string" } }, "additionalProperties": false, "required": ["session_id"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/users/transfer": { "post": { "summary": "Transfer workspace user content", "operationId": "transfer-user-content", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_user_id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the source user to transfer content from." }, "to_user_id": { "$ref": "#/components/schemas/idRequest", "description": "The ID of the destination user to transfer content to." }, "content_types": { "type": "array", "items": { "type": "string", "enum": ["pages", "agents"], "description": "One of: `pages`, `agents`" }, "maxItems": 100, "description": "What content types to transfer. Defaults to pages for backwards compatibility." } }, "required": ["from_user_id", "to_user_id"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "content_transfer", "description": "The content transfer object type name." } }, "additionalProperties": false, "required": ["object"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/pages/{page_id}/unshare_from_web": { "post": { "summary": "Unshare a page from web", "operationId": "unshare-page-from-web", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest" } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/pageObjectResponse" }, { "$ref": "#/components/schemas/partialPageObjectResponse" } ] }, { "anyOf": [ { "$ref": "#/components/schemas/partialBlockObjectResponse" }, { "$ref": "#/components/schemas/blockObjectResponse" } ] }, { "anyOf": [ { "$ref": "#/components/schemas/partialDataSourceObjectResponse" }, { "$ref": "#/components/schemas/dataSourceObjectResponse" } ] } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/agents/{agent_id}/credit_limit": { "patch": { "summary": "Update agent credit limit", "operationId": "update-agent-credit-limit", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The ID of the custom agent (a UUID). The personal agent (Notion AI) is not supported by this endpoint." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credit_limit": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "The per-agent credit limit as a non-negative integer, or null to clear the limit." } }, "additionalProperties": false, "required": ["credit_limit"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "$ref": "#/components/schemas/idResponse" }, "credit_limit": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The agent's editor-set per-agent credit limit; null when no limit applies." }, "last_edited_time": { "type": "string", "description": "ISO 8601 timestamp of when the agent was last edited." } }, "additionalProperties": false, "required": ["agent_id", "credit_limit", "last_edited_time"] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/agents/{agent_id}/status": { "patch": { "summary": "Update agent status", "operationId": "update-agent-status", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": ["notion_ai", "33333333-3333-3333-3333-333333333333"], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ], "description": "The agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply." } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["active", "disabled"], "description": "Set to \"active\" to re-enable an agent that was disabled through this API, or \"disabled\" to turn off a running agent." } }, "additionalProperties": false, "required": ["status"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "$ref": "#/components/schemas/idResponse" }, "status": { "type": "string", "enum": ["active", "disabled", "deleted"], "description": "\"active\" when the agent can run; \"disabled\" when it is paused (see pause_reason); \"deleted\" when it has been removed." }, "pause_reason": { "oneOf": [ { "type": "string", "enum": [ "run_limit", "credit_limit", "runaway_credit_usage", "workspace_credit_limit", "failure_limit", "mark_session_failed_autopause", "disabled_from_workspace_settings", "disabled_from_api", "disabled_from_agent_settings", "disabled_due_to_no_members_with_access", "disabled_due_to_lack_of_editors", "disabled_by_notion", "internal_error", "needs_user_review", "tool_unavailable" ], "description": "One of: `run_limit`, `credit_limit`, `runaway_credit_usage`, `workspace_credit_limit`, `failure_limit`, `mark_session_failed_autopause`, `disabled_from_workspace_settings`, `disabled_from_api`, `disabled_from_agent_settings`, `disabled_due_to_no_members_with_access`, `disabled_due_to_lack_of_editors`, `disabled_by_notion`, `internal_error`, `needs_user_review`, `tool_unavailable`" }, { "type": "null" } ], "description": "Why the agent is paused when status is \"disabled\" (e.g. \"disabled_from_api\", \"credit_limit\"); null when active or deleted." }, "last_edited_time": { "type": "string", "description": "ISO 8601 timestamp of when the agent was last edited." } }, "additionalProperties": false, "required": [ "agent_id", "status", "pause_reason", "last_edited_time" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/_/pages/{page_id}/permissions": { "patch": { "summary": "Update page permissions", "operationId": "private-update-page-permissions", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/idRequest" } }, { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "role": { "type": "string", "enum": [ "full_owner", "can_edit", "can_comment", "can_view" ] }, "type": { "type": "string", "const": "user_permission" }, "user_id": { "type": "string", "format": "uuid" } }, "required": ["role", "type", "user_id"] }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "full_owner", "can_edit", "can_comment", "can_view" ] }, "type": { "type": "string", "const": "group_permission" }, "group_id": { "type": "string", "format": "uuid" } }, "required": ["role", "type", "group_id"] }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "full_owner", "can_edit", "can_comment", "can_view" ] }, "type": { "type": "string", "const": "teamspace_owner" } }, "required": ["role", "type"] }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "full_owner", "can_edit", "can_comment", "can_view" ] }, "type": { "type": "string", "const": "teamspace_members" } }, "required": ["role", "type"] }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "full_owner", "can_edit", "can_comment", "can_view" ] }, "type": { "type": "string", "const": "workspace_permission" }, "discoverability": { "type": "string", "enum": ["discoverable", "unlisted"] } }, "required": ["role", "type", "discoverability"] } ] } }, "is_restricted": { "type": "boolean" } }, "additionalProperties": false, "required": ["permissions"] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/pageObjectResponse" }, { "$ref": "#/components/schemas/partialPageObjectResponse" } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/sessions": { "post": { "summary": "Update a session", "operationId": "update-session", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "maxLength": 10000 }, "agent_id": { "oneOf": [ { "$ref": "#/components/schemas/idRequest" }, { "type": "string", "enum": [ "notion_ai", "33333333-3333-3333-3333-333333333333" ], "description": "One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`" } ] }, "session_id": { "$ref": "#/components/schemas/idRequest" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_upload": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 200 } }, "additionalProperties": false, "required": ["id"] }, "type": { "type": "string", "const": "file_upload", "description": "Always `file_upload`" }, "name": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false, "required": ["file_upload"] }, "maxItems": 100 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } }, "prompt_context": { "type": "string", "maxLength": 10000 } }, "additionalProperties": false, "required": ["message"] }, { "type": "object", "properties": { "session_id": { "$ref": "#/components/schemas/idRequest" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "$ref": "#/components/schemas/idRequest" }, "option_id": { "type": "string", "enum": ["approve", "reject"], "description": "One of: `approve`, `reject`" } }, "additionalProperties": false, "required": ["action_id", "option_id"] }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } } }, "additionalProperties": false, "required": ["session_id", "actions"] }, { "type": "object", "properties": { "session_id": { "$ref": "#/components/schemas/idRequest" }, "continue_from": { "type": "string", "maxLength": 200 } }, "additionalProperties": false, "required": ["session_id", "continue_from"] } ], "title": "Update session request", "description": "Exactly one mode: append a message, answer pending actions, or replay from an event." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "session", "description": "Always `session`" }, "id": { "type": "string" }, "agent_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "requires_action", "completed", "failed", "canceled", "terminated" ], "description": "One of: `queued`, `in_progress`, `requires_action`, `completed`, `failed`, `canceled`, `terminated`" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "required_actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["approve", "reject"], "description": "One of: `approve`, `reject`" }, "label": { "type": "string" } }, "additionalProperties": false, "required": ["id", "label"] }, "maxItems": 100 } }, "additionalProperties": false, "required": ["action_id", "title", "options"] }, "maxItems": 100 }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false, "required": ["code", "message", "retryable"] } }, "additionalProperties": false, "required": [ "object", "id", "agent_id", "title", "status", "created_at", "updated_at" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } }, "/v1/workspace/search": { "post": { "summary": "Search a workspace", "operationId": "search-workspace", "tags": ["Internal"], "x-hidden": true, "x-noIndex": true, "parameters": [ { "$ref": "#/components/parameters/notionVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "anyOf": [ { "type": "string" }, { "anyOf": [ { "type": "object", "properties": { "and": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": ["and"] }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": ["or"] } ] }, { "type": "object", "properties": { "title": { "type": "string" } }, "additionalProperties": false, "required": ["title"] }, { "type": "null" } ] }, "shared_with_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "location": { "type": "object", "properties": {}, "additionalProperties": false }, "date_range_filter": { "type": "object", "properties": {}, "additionalProperties": false }, "options": { "type": "object", "properties": {}, "additionalProperties": false }, "start_cursor": { "type": "string", "format": "uuid" }, "page_size": { "type": "number" }, "result_type": { "type": "string", "enum": ["page", "database"] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "title": "Search Result", "type": "object", "properties": { "type": { "type": "string", "const": "search_result" }, "search_result": { "$ref": "#/components/schemas/emptyObject" }, "object": { "type": "string", "const": "list" }, "next_cursor": { "type": ["string", "null"] }, "has_more": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "search_result" }, "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "created_time": { "type": "number" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/partialUserObjectResponse" }, { "$ref": "#/components/schemas/userObjectResponse" } ] }, "last_edited_by": { "anyOf": [ { "$ref": "#/components/schemas/partialUserObjectResponse" }, { "$ref": "#/components/schemas/userObjectResponse" } ] }, "last_edited_time": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean" }, "teamspace_id": { "type": ["string", "null"], "format": "uuid" }, "teamspace_name": { "type": ["string", "null"] }, "space_id": { "type": "string", "format": "uuid" }, "space_name": { "type": "string" }, "title": { "type": "string" }, "result_type": { "type": "string", "enum": ["database", "page"] } }, "required": [ "object", "id", "path", "created_time", "created_by", "last_edited_by", "last_edited_time", "deleted", "teamspace_id", "teamspace_name", "space_id", "space_name", "title", "result_type" ] } }, "total": { "type": "number" } }, "required": [ "type", "search_result", "object", "next_cursor", "has_more", "results", "total" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_400" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_401" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_403" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_404" } } } }, "406": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_406" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_409" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_429" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_500" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_503" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_504" } } } }, "529": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_api_529" } } } } } } } } }