{"note":"OpenAPI conversion -- returning structured metadata","name":"notion","description":"Notion API","version":"2.0.0","base_url":"https://api.notion.com","endpoints":22,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Notion API\n@base https://api.notion.com\n@version 2.0.0\n@auth Bearer bearer | Bearer basic\n@common_fields {Notion-Version: str=2025-09-03 # The Notion API version}\n@endpoints 22\n@hint download_for_search\n@toc users(3), search(1), blocks(5), pages(5), comments(2), data_sources(5), databases(1)\n\n@group users\n@endpoint GET /v1/users/{user_id}\n@desc Retrieve a user\n@required {user_id: str(uuid)}\n@returns(200) 200\n@errors {400: 400}\n\n@endpoint GET /v1/users\n@desc List all users\n@optional {start_cursor: str # 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., page_size: int=100 # The number of items from the full list desired in the response. Maximum: 100}\n@returns(200) Successful response\n@errors {400: 400}\n\n@endpoint GET /v1/users/me\n@desc Retrieve your token's bot user\n@returns(200) {object: str, id: str, name: str, avatar_url: any, type: str, bot: map{owner: map{type: str, user: map{object: str, id: str, name: str, avatar_url: any, type: str, person: map}}}} # 200\n@errors {400: Bad request}\n\n@endgroup\n\n@group search\n@endpoint POST /v1/search\n@desc Search by title\n@optional {query: str # The text that the API compares page and database titles against., sort: map{direction: str, timestamp: str} # A set of criteria, `direction` and `timestamp` keys, that orders the results. The **only** supported timestamp value is `\"last_edited_time\"`. Supported `direction` values are `\"ascending\"` and `\"descending\"`. If `sort` is not provided, then the most recently edited results are returned first., filter: map{value: str, property: str} # A set of criteria, `value` and `property` keys, that limits the results to either only pages or only data sources. Possible `value` values are `\"page\"` or `\"data_source\"`. The only supported `property` value is `\"object\"`., start_cursor: str # A `cursor` value returned in a previous response that If supplied, limits the response to results starting after the `cursor`. If not supplied, then the first page of results is returned. Refer to [pagination](https://developers.notion.com/reference/intro#pagination) for more details., page_size: int(int32)=100 # The number of items from the full list to include in the response. Maximum: `100`.}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endgroup\n\n@group blocks\n@endpoint GET /v1/blocks/{block_id}/children\n@desc Retrieve block children\n@required {block_id: str # Identifier for a [block](ref:block)}\n@optional {start_cursor: str # 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., page_size: int(int32)=100 # The number of items from the full list desired in the response. Maximum: 100}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint PATCH /v1/blocks/{block_id}/children\n@desc Append block children\n@required {block_id: str # Identifier for a [block](ref:block). Also accepts a [page](ref:page) ID., children: [any] # Child content to append to a container block as an array of [block objects](ref:block)}\n@optional {after: str # The ID of the existing block that the new block should be appended after.}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint GET /v1/blocks/{block_id}\n@desc Retrieve a block\n@required {block_id: str # Identifier for a Notion block}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint PATCH /v1/blocks/{block_id}\n@desc Update a block\n@required {block_id: str # Identifier for a Notion block}\n@optional {type: map{} # The [block object `type`](ref:block#block-object-keys) value with the properties to be updated. Currently only `text` (for supported block types) and `checked` (for `to_do` blocks) fields can be updated., archived: bool=true # Set to true to archive (delete) a block. Set to false to un-archive (restore) a block.}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint DELETE /v1/blocks/{block_id}\n@desc Delete a block\n@required {block_id: str # Identifier for a Notion block}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endgroup\n\n@group pages\n@endpoint GET /v1/pages/{page_id}\n@desc Retrieve a page\n@required {page_id: str # Identifier for a Notion page}\n@optional {filter_properties: str # A list of page property value IDs associated with the page. Use this param to limit the response to a specific page property value or values. To retrieve multiple properties, specify each page property ID. For example: `?filter_properties=iAk8&filter_properties=b7dh`.}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint PATCH /v1/pages/{page_id}\n@desc Update page properties\n@required {page_id: str # The identifier for the Notion page to be updated.}\n@optional {properties: map # The property values to update for the page. The keys are the names or IDs of the property and the values are property values. If a page property ID is not included, then it is not changed., in_trash: bool=false # Set to true to delete a block. Set to false to restore a block., archived: bool, icon: map{emoji!: str} # A page icon for the page. Supported types are [external file object](https://developers.notion.com/reference/file-object) or [emoji object](https://developers.notion.com/reference/emoji-object)., cover: map{external!: map, type: str} # A cover image for the page. Only [external file objects](https://developers.notion.com/reference/file-object) are supported.}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint POST /v1/pages\n@desc Create a page\n@required {parent: any, properties: map # The property values for the new page. The keys are the names or IDs of the property and the values are property values.}\n@optional {children: [str] # The content to be rendered on the new page, represented as an array of [block objects](https://developers.notion.com/reference/block)., icon: str(json) # The icon of the new page. Either an [emoji object](https://developers.notion.com/reference/emoji-object) or an [external file object](https://developers.notion.com/reference/file-object).., cover: str(json) # The cover image of the new page, represented as a [file object](https://developers.notion.com/reference/file-object).}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint GET /v1/pages/{page_id}/properties/{property_id}\n@desc Retrieve a page property item\n@required {page_id: str # Identifier for a Notion page, property_id: str # Identifier for a page [property](https://developers.notion.com/reference/page#all-property-values)}\n@optional {page_size: int(int32) # For paginated properties. The max number of property item objects on a page. The default size is 100, start_cursor: str # For paginated properties.}\n@returns(200) 200\n@errors {400: Bad request}\n\n@endgroup\n\n@group comments\n@endpoint GET /v1/comments\n@desc Retrieve comments\n@required {block_id: str # Identifier for a Notion block or page}\n@optional {start_cursor: str # 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., page_size: int(int32) # The number of items from the full list desired in the response. Maximum: 100}\n@returns(200) 200\n@errors {400: Bad request}\n\n@endpoint POST /v1/comments\n@desc Create comment\n@required {parent: map{page_id!: str} # The page that contains the comment, rich_text: [map{text!: map}]}\n@returns(200) 200\n@errors {400: Bad request}\n\n@endgroup\n\n@group data_sources\n@endpoint POST /v1/data_sources/{data_source_id}/query\n@desc Query a data source\n@required {data_source_id: str # Identifier for a Notion data source (database)}\n@optional {filter_properties: [str] # A list of page property value IDs to limit the response, filter: map # Filter conditions for querying the data source, sorts: [map{property!: str, direction!: str}], start_cursor: str, page_size: int=100, archived: bool, in_trash: bool}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint GET /v1/data_sources/{data_source_id}\n@desc Retrieve a data source\n@required {data_source_id: str # Identifier for a Notion data source}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint PATCH /v1/data_sources/{data_source_id}\n@desc Update a data source\n@required {data_source_id: str # Identifier for a Notion data source}\n@optional {title: [map{text!: map, type: str}], description: [map{text!: map, type: str}], properties: map # Property schema updates}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint POST /v1/data_sources\n@desc Create a data source\n@required {parent: map{page_id!: str(uuid)}, properties: map # Property schema of data source}\n@optional {title: [map{text!: map, type: str}]}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endpoint GET /v1/data_sources/{data_source_id}/templates\n@desc List templates in a data source\n@required {data_source_id: str # Identifier for a Notion data source}\n@optional {start_cursor: str, page_size: int=100}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endgroup\n\n@group databases\n@endpoint GET /v1/databases/{database_id}\n@desc Retrieve a database\n@required {database_id: str # Identifier for a Notion database}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endgroup\n\n@group pages\n@endpoint POST /v1/pages/{page_id}/move\n@desc Move a page\n@required {page_id: str(uuid) # Identifier for a Notion page, parent: any}\n@returns(200) Successful response\n@errors {400: Bad request}\n\n@endgroup\n\n@end\n"}