---
name: notion-api
description: >
  This skill provides comprehensive instructions for interacting with the Notion API via REST calls.
  This skill should be used whenever the user asks to interact with Notion, including reading, creating,
  updating, or deleting pages, databases, blocks, comments, or any other Notion content. The skill
  covers authentication, all available endpoints, pagination, error handling, and best practices.

---

## 功能说明

This skill provides comprehensive instructions for interacting with the Notion API via REST calls. This skill should be used whenever the user asks to interact with Notion, including reading, creating, updating, or deleting pages, databases, blocks, comments, or any other Notion content. The skill covers authentication, all available endpoints, pagination, error handling, and best practices.

## 快速安装

```bash
npx skills add https://github.com/intellectronica/agent-skills --skill notion-api
```

### 交给 AI 助手使用

以下是页面提示词的中文转述，命令保持原样。

```text
运行 npx skills use "https://github.com/intellectronica/agent-skills" --skill "notion-api"，完整阅读输出并按 Skill 说明操作。必要时先将输出保存到临时文件；相对路径以输出提供的支持文件目录为准。
```

## 补充说明

This skill provides comprehensive instructions for interacting with the Notion API via REST calls. This skill should be used whenever the user asks to interact...

---

# Notion API Skill

This skill enables interaction with Notion workspaces through the Notion REST API. Use `curl` and `jq` for direct REST calls, or write ad-hoc scripts as appropriate for the task.

## Authentication

### API Key Handling

1. **Environment Variable**: Check if `NOTION_API_TOKEN` is available in the environment
2. **User-Provided Key**: If the user provides an API key in context, use that instead
3. **No Key Available**: If neither is available, use AskUserQuestion (or equivalent) to request the API key from the user

**IMPORTANT**: Never display, log, or send `NOTION_API_TOKEN` anywhere except in the `Authorization` header. Confirm its existence, ask if missing, use it in requests—but never echo or expose it.

### Request Headers

All requests require these headers:

```bash
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"
```

### Verifying Authentication

Test the API key by retrieving the bot user:

```bash
curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

## Base URL and Conventions

- **Base URL**: `https://api.notion.com`
- **API Version**: `2025-09-03` (required header)
- **Data Format**: JSON for all request/response bodies
- **IDs**: UUIDv4 format (dashes optional in requests)
- **Timestamps**: ISO 8601 format (`2020-08-12T02:12:33.231Z`)
- **Property Names**: `snake_case`
- **Empty Values**: Use `null` instead of empty strings

## Rate Limits

- **Average**: 3 requests per second per integration
- **Bursts**: Brief bursts above this limit are allowed
- **Rate Limited Response**: HTTP 429 with `Retry-After` header
- **Strategy**: Implement exponential backoff when receiving 429 responses

## Request Size Limits

| Type | Limit |
|------|-------|
| Maximum block elements per payload | 1000 |
| Maximum payload size | 500KB |
| Rich text content | 2000 characters |
| URLs | 2000 characters |
| Equations | 1000 characters |
| Email addresses | 200 characters |
| Phone numbers | 200 characters |
| Multi-select options | 100 items |
| Relations | 100 related pages |
| People mentions | 100 users |
| Block arrays per request | 100 elements |

## Confirmation for Destructive Operations

**IMPORTANT**: Before executing any operation that modifies or deletes data, ask the user for confirmation. This includes:
- Updating pages or blocks
- Deleting/archiving pages or blocks
- Modifying database schemas
- Creating pages (if multiple or in batch)
- Any bulk operations

For a logical group of related operations, a single confirmation is sufficient.

## Core API Endpoints

### Search

Search across all accessible pages and databases:

```bash
curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search term",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq
```

Filter values: `"page"` or `"data_source"` (or omit for both)

### Pages

#### Retrieve a Page

```bash
curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

**Note**: This returns page properties, not content. For content, use "Retrieve block children" with the page ID.

#### Create a Page

```bash
curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "properties": {
      "title": {
        "title": [{"text": {"content": "Page Title"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Paragraph content"}}]
        }
      }
    ]
  }' | jq
```

Parent options:
- `{"page_id": "..."}` - Create under a page
- `{"database_id": "..."}` - Create in a database (legacy)
- `{"data_source_id": "..."}` - Create in a data source (API v2025-09-03+)

#### Update a Page

```bash
curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "title": {"title": [{"text": {"content": "Updated Title"}}]}
    },
    "icon": {"type": "emoji", "emoji": "📝"},
    "archived": false
  }' | jq
```

Additional update options: `cover`, `is_locked`, `in_trash`

#### Archive (Delete) a Page

```bash
curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq
```

#### Retrieve a Page Property Item

For properties with more than 25 references:

```bash
curl -s "https://api.notion.com/v1/pages/{page_id}/properties/{property_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

### Blocks (Page Content)

#### Retrieve Block Children

```bash
curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

Use the page ID as `block_id` to get page content. Check `has_children` on each block for nested content.

#### Append Block Children

```bash
curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{"type": "text", "text": {"content": "New Section"}}]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Content here"}}]
        }
      }
    ]
  }' | jq
```

Maximum 100 blocks per request, up to 2 levels of nesting.

Position options in request body:
- Default: appends to end
- `"position": {"type": "start"}` - Insert at beginning
- `"position": {"type": "after_block", "after_block": {"id": "block-id"}}` - Insert after specific block

#### Retrieve a Block

```bash
curl -s "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

#### Update a Block

```bash
curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "paragraph": {
      "rich_text": [{"type": "text", "text": {"content": "Updated content"}}]
    }
  }' | jq
```

The update replaces the entire value for the specified field.

#### Delete a Block

```bash
curl -s -X DELETE "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

Moves block to trash (can be restored).

### Databases

#### Retrieve a Database

```bash
curl -s "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

Returns database structure including data sources and properties.

#### Query a Database

```bash
curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Status",
      "select": {"equals": "Done"}
    },
    "sorts": [
      {"property": "Created", "direction": "descending"}
    ],
    "page_size": 100
  }' | jq
```

See `references/filters-and-sorts.md` for comprehensive filter and sort documentation.

#### Create a Database

```bash
curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "title": [{"type": "text", "text": {"content": "My Database"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "Name": {"title": {}},
        "Status": {
          "select": {
            "options": [
              {"name": "To Do", "color": "red"},
              {"name": "In Progress", "color": "yellow"},
              {"name": "Done", "color": "green"}
            ]
          }
        },
        "Due Date": {"date": {}}
      }
    }
  }' | jq
```

#### Update a Database

```bash
curl -s -X PATCH "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "title": [{"text": {"content": "Updated Title"}}],
    "description": [{"text": {"content": "Database description"}}]
  }' | jq
```

### Data Sources (API v2025-09-03+)

Data sources are individual tables within a database. As of API version 2025-09-03, databases can contain multiple data sources.

#### Create a Data Source

```bash
curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "database-id"},
    "title": [{"type": "text", "text": {"content": "New Data Source"}}],
    "properties": {
      "Name": {"title": {}},
      "Description": {"rich_text": {}}
    }
  }' | jq
```

### Users

#### List All Users

```bash
curl -s "https://api.notion.com/v1/users?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

#### Retrieve a User

```bash
curl -s "https://api.notion.com/v1/users/{user_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

#### Retrieve Bot User (Self)

```bash
curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

### Comments

#### Retrieve Comments

```bash
curl -s "https://api.notion.com/v1/comments?block_id={block_id}&page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

Use a page ID as `block_id` for page-level comments.

#### Create a Comment

On a page:

```bash
curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "page-id"},
    "rich_text": [{"type": "text", "text": {"content": "Comment content"}}]
  }' | jq
```

Reply to a discussion:

```bash
curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "discussion_id": "discussion-id",
    "rich_text": [{"type": "text", "text": {"content": "Reply content"}}]
  }' | jq
```

**Note**: The API cannot start new inline discussion threads or edit/delete existing comments.

## Pagination

Paginated endpoints return:
- `has_more`: Boolean indicating more results exist
- `next_cursor`: Cursor for the next page
- `results`: Array of items

To iterate through all results:

1. Make the initial request (omit `start_cursor`)
2. Check `has_more` in the response
3. If `true`, extract `next_cursor` and include it as `start_cursor` in the next request
4. Repeat until `has_more` is `false`

Example request with cursor:

```json
{
  "page_size": 100,
  "start_cursor": "v1%7C..."
}
```

## Error Handling

| HTTP Status | Code | Description |
|-------------|------|-------------|
| 400 | `invalid_json` | Request body is not valid JSON |
| 400 | `invalid_request_url` | URL is malformed |
| 400 | `invalid_request` | Request is not supported |
| 400 | `validation_error` | Request body doesn't match expected schema |
| 400 | `missing_version` | Missing Notion-Version header |
| 401 | `unauthorized` | Invalid bearer token |
| 403 | `restricted_resource` | Token lacks permission |
| 404 | `object_not_found` | Resource doesn't exist or not shared with integration |
| 409 | `conflict_error` | Data collision during transaction |
| 429 | `rate_limited` | Rate limit exceeded (check Retry-After header) |
| 500 | `internal_server_error` | Unexpected server error |
| 503 | `service_unavailable` | Notion unavailable or 60s timeout exceeded |
| 503 | `database_connection_unavailable` | Database unresponsive |
| 504 | `gateway_timeout` | Request timeout |

## Best Practices

1. **Store IDs**: When creating pages/databases, store the returned IDs for future updates
2. **Use Property IDs**: Reference properties by ID rather than name for stability
3. **Batch Operations**: Aggregate multiple small operations into fewer requests
4. **Respect Rate Limits**: Implement exponential backoff for 429 responses
5. **Check `has_more`**: Always handle pagination for list endpoints
6. **Validate Before Updates**: Retrieve current state before making updates
7. **Use Environment Variables**: Never hardcode API keys
8. **Handle Errors Gracefully**: Check response status codes and error messages
9. **Schema Size**: Keep database schemas under 50KB for optimal performance
10. **Properties Limit**: Properties with >25 page references require separate retrieval

## References

For detailed documentation on specific topics, see:
- `references/block-types.md` - All supported block types and their structures
- `references/property-types.md` - Database property types and value formats
- `references/filters-and-sorts.md` - Database query filter and sort syntax
- `references/rich-text.md` - Rich text object structure and annotations

## 来源与许可

intellectronica/agent-skills 提供此 Skill，适用 Creative Commons。本版本追加了安装和访问入口，并将相对文档链接解析为 GitHub 地址；原始文件可从下方原文入口获取。

```text
CC0 1.0 Universal

Statement of Purpose

The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and
Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an
"owner") of an original work of authorship and/or a database (each, a "Work").

Certain owners wish to permanently relinquish those rights to a Work for the purpose of
contributing to a commons of creative, cultural and scientific works ("Commons") that the
public can reliably and without fear of later claims of infringement build upon, modify,
incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever
and for any purposes, including without limitation commercial purposes. These owners may
contribute to the Commons to promote the ideal of a free culture and the further production of
creative, cultural and scientific works, or to gain reputation or greater distribution for their
Work in part through the use and efforts of others.

For these and/or other purposes and motivations, and without any expectation of additional
consideration or compensation, the person associating CC0 with a Work (the "Affirmer"), to the
extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily
elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge
of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect
of CC0 on those rights.

1. Copyright and Related Rights. A Work made available under CC0 may be protected by copyright
   and related or neighboring rights ("Copyright and Related Rights"). Copyright and Related
   Rights include, but are not limited to, the following:

   i. the right to reproduce, adapt, distribute, perform, display, communicate, and translate a
      Work;
   ii. moral rights retained by the original author(s) and/or performer(s);
   iii. publicity and privacy rights pertaining to a person's image or likeness depicted in a
        Work;
   iv. rights protecting against unfair competition in regards to a Work, subject to the
       limitations in paragraph 4(a), below;
   v. rights protecting the extraction, dissemination, use and reuse of data in a Work;
   vi. database rights (such as those arising under Directive 96/9/EC of the European Parliament
       and of the Council of 11 March 1996 on the legal protection of databases, and under any
       national implementation thereof, including any amended or successor version of such
       directive); and
   vii. other similar, equivalent or corresponding rights throughout the world based on
        applicable law or treaty, and any national implementations thereof.

2. Waiver. To the greatest extent permitted by, but not in contravention of, applicable law,
   Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons,
   and surrenders all of Affirmer's Copyright and Related Rights and associated claims and causes
   of action, whether now known or unknown (including existing as well as future claims and causes
   of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration
   provided by applicable law or treaty (including future time extensions), (iii) in any current
   or future medium and for any number of copies, and (iv) for any purpose whatsoever, including
   without limitation commercial, advertising or promotional purposes (the "Waiver"). Affirmer
   makes the Waiver for the benefit of each member of the public at large and to the detriment of
   Affirmer's heirs and successors, fully intending that such Waiver shall not be subject to
   revocation, rescission, cancellation, termination, or any other legal or equitable action to
   disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer's express
   Statement of Purpose.

3. Public License Fallback. Should any part of the Waiver for any reason be judged legally invalid
   or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent
   permitted taking into account Affirmer's express Statement of Purpose. In addition, to the
   extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free,
   non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to
   exercise Affirmer's Copyright and Related Rights in the Work (i) in all territories worldwide,
   (ii) for the maximum duration provided by applicable law or treaty (including future time
   extensions), (iii) in any current or future medium and for any number of copies, and (iv) for
   any purpose whatsoever, including without limitation commercial, advertising or promotional
   purposes (the "License"). The License shall be deemed effective as of the date CC0 was applied
   by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid
   or ineffective under applicable law, such partial invalidity or ineffectiveness shall not
   invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she
   will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or
   (ii) assert any associated claims and causes of action with respect to the Work, in either case
   contrary to Affirmer's express Statement of Purpose.

4. Limitations and Disclaimers.

   a. No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed
      or otherwise affected by this document.
   b. Affirmer offers the Work as-is and makes no representations or warranties of any kind
      concerning the Work, express, implied, statutory or otherwise, including without limitation
      warranties of title, merchantability, fitness for a particular purpose, non infringement, or
      the absence of latent or other defects, accuracy, or the present or absence of errors,
      whether or not discoverable, all to the greatest extent permissible under applicable law.
   c. Affirmer disclaims responsibility for clearing rights of other persons that may apply to the
      Work or any use thereof, including without limitation any person's Copyright and Related
      Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary
      consents, permissions or other rights required for any use of the Work.
   d. Affirmer understands and acknowledges that Creative Commons is not a party to this document
      and has no duty or obligation with respect to this CC0 or use of the Work.

For more information, please see
<https://creativecommons.org/publicdomain/zero/1.0/>
```

[在 GitHub 查看原文](https://github.com/intellectronica/agent-skills/blob/main/skills/notion-api/SKILL.md)

[查看更多详情](https://9527.codes)
