{"files":{"SKILL.md":"---\nname: notion-api\ndescription: \"Notion API skill. Use when working with Notion for users, search, blocks. Covers 22 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Notion API\nAPI version: 2.0.0\n\n## Auth\nBearer bearer | Bearer basic\n\n## Base URL\nhttps://api.notion.com\n\n## Setup\n1. Set Authorization header with Bearer token\n2. GET /v1/users -- list all users\n3. POST /v1/search -- create first search\n\n## Endpoints\n22 endpoints across 7 groups. See references/api-spec.lap for full details.\n\n### Users\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /v1/users/{user_id} | Retrieve a user |\n| GET | /v1/users | List all users |\n| GET | /v1/users/me | Retrieve your token's bot user |\n\n### Search\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /v1/search | Search by title |\n\n### Blocks\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /v1/blocks/{block_id}/children | Retrieve block children |\n| PATCH | /v1/blocks/{block_id}/children | Append block children |\n| GET | /v1/blocks/{block_id} | Retrieve a block |\n| PATCH | /v1/blocks/{block_id} | Update a block |\n| DELETE | /v1/blocks/{block_id} | Delete a block |\n\n### Pages\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /v1/pages/{page_id} | Retrieve a page |\n| PATCH | /v1/pages/{page_id} | Update page properties |\n| POST | /v1/pages | Create a page |\n| GET | /v1/pages/{page_id}/properties/{property_id} | Retrieve a page property item |\n| POST | /v1/pages/{page_id}/move | Move a page |\n\n### Comments\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /v1/comments | Retrieve comments |\n| POST | /v1/comments | Create comment |\n\n### Data_sources\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /v1/data_sources/{data_source_id}/query | Query a data source |\n| GET | /v1/data_sources/{data_source_id} | Retrieve a data source |\n| PATCH | /v1/data_sources/{data_source_id} | Update a data source |\n| POST | /v1/data_sources | Create a data source |\n| GET | /v1/data_sources/{data_source_id}/templates | List templates in a data source |\n\n### Databases\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /v1/databases/{database_id} | Retrieve a database |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"Get user details?\" -> GET /v1/users/{user_id}\n- \"List all users?\" -> GET /v1/users\n- \"List all me?\" -> GET /v1/users/me\n- \"Create a search?\" -> POST /v1/search\n- \"List all children?\" -> GET /v1/blocks/{block_id}/children\n- \"Get block details?\" -> GET /v1/blocks/{block_id}\n- \"Partially update a block?\" -> PATCH /v1/blocks/{block_id}\n- \"Delete a block?\" -> DELETE /v1/blocks/{block_id}\n- \"Get page details?\" -> GET /v1/pages/{page_id}\n- \"Partially update a page?\" -> PATCH /v1/pages/{page_id}\n- \"Create a page?\" -> POST /v1/pages\n- \"Get property details?\" -> GET /v1/pages/{page_id}/properties/{property_id}\n- \"List all comments?\" -> GET /v1/comments\n- \"Create a comment?\" -> POST /v1/comments\n- \"Create a query?\" -> POST /v1/data_sources/{data_source_id}/query\n- \"Get data_source details?\" -> GET /v1/data_sources/{data_source_id}\n- \"Partially update a data_source?\" -> PATCH /v1/data_sources/{data_source_id}\n- \"Create a data_source?\" -> POST /v1/data_sources\n- \"List all templates?\" -> GET /v1/data_sources/{data_source_id}/templates\n- \"Get database details?\" -> GET /v1/databases/{database_id}\n- \"Create a move?\" -> POST /v1/pages/{page_id}/move\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n- Error responses include status codes and descriptions in the spec\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@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"}}