{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

ý niệm

API Notion + ntn CLI: trang, cơ sở dữ liệu, đánh dấu, Công nhân.

Siêu dữ liệu kỹ năng

Nguồn	Đi kèm (được cài đặt theo mặc định)
Đường dẫn

skills/productivity/notion ` | | Phiên bản |

2.0.0 ` | | Tác giả | cộng đồng | | Giấy phép | MIT | | Nền tảng | Linux, macOS, Windows | | Thẻ |

Notion

, `Productivity

, `Notes

, `Database

, `API

, `CLI

, Workers |

Tham khảo: đầy đủ SKILL.md

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

ý niệm

Nói chuyện với Notion theo hai cách. Mã thông báo tích hợp giống nhau hoạt động cho cả hai — hãy chọn theo những gì có sẵn.◆ ** ntn CLI** — CLI chính thức của Notion. Cú pháp ngắn hơn, tải lên tệp một dòng, bắt buộc đối với Công nhân. chỉ macOS + Linux kể từ tháng 5 năm 2026 (Sắp có hỗ trợ Windows). **Mặc định khi cài đặt.** ◆ **HTTP + Curl** — hoạt động ở mọi nơi kể cả Windows. **Dự phòng mặc định** khi chưa cài đặt ntn

.

Thiết lập

1. Nhận mã thông báo tích hợp (bắt buộc cho cả hai đường dẫn)

1. Tạo tiện ích tích hợp tại https://notion.so/my-integrations
2. Sao chép khóa API (bắt đầu bằng ntn_ hoặc `secret_

) 3. Lưu trữ trong

~/.Hermes/.env

:

` NOTION_API_KEY=ntn_your_key_here

` 4. Chia sẻ các trang/cơ sở dữ liệu mục tiêu với sự tích hợp trong Ký hiệu: menu trang

... → Connect to ` → tên tích hợp của bạn. Nếu không có điều này, API sẽ trả về 404 cho trang đó mặc dù nó tồn tại.

2. Cài đặt

ntn (đường dẫn ưu tiên trên macOS/Linux)

# Recommended
curl -fSSL https://ntn.dev | bash

# Or via npm (needs Node 22+, npm 10+)
npm install --global ntn`ntn --version    # verify

`
``**Bỏ qua 
`ntn login
` — thay vào đó hãy sử dụng mã thông báo tích hợp.** Tính năng này hoạt động không cần đầu óc, không cần trình duyệt:

`
``` bash
 export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn reads NOTION_API_TOKEN
 export NOTION_KEYRING=0                       # don't try to use the OS keychain

`
``Thêm các bản xuất đó vào hồ sơ shell của bạn (hoặc vào 

~/.Hermes/.env

) để mỗi phiên đều kế thừa chúng.

### 3. Chọn đường dẫn khi chạy

`bash
if command -v ntn >/dev/null 2>&1; then

  # use ntn
else
  # fall back to curl
fi

`
``Người dùng Windows: bỏ qua hoàn toàn bước 2 cho đến khi 
`ntn
` gốc xuất xưởng — Đường dẫn B hoạt động tốt. Nếu bạn muốn sử dụng CLI ngay bây giờ, hãy cài đặt 
`ntn
` bên trong WSL2.

## API cơ bản``Notion-Version: 2025-09-03
` được yêu cầu trên tất cả các yêu cầu HTTP. 
`ntn
` xử lý việc này cho bạn. Trong phiên bản này, những gì người dùng gọi là "cơ sở dữ liệu" được gọi là **nguồn dữ liệu** trong API.

## Đường dẫn A — 
`ntn
` CLI (ưu tiên, macOS / Linux)

### Lệnh gọi API thô (viết tắt của Curl)

`
``` bash
ntn API v1/users                                  # GET
ntn API v1/pages parent[page_id]=abc123 \         # POST with inline body
  properties[title][0][text][content]="Notes"
ntn API v1/pages/abc123 -X PATCH archived:=true   # PATCH; := is non-string (bool/num/null)

`
``Ghi chú cú pháp:

- 
`key=value

 - trường chuỗi
- 
`key[nested]=value

 - trường đối tượng lồng nhau
- 
`key:=value

 - bài tập đã gõ (booleans, số, null, mảng)

### Tìm kiếm

`
``` bash
ntn API v1/search query="page title"

`

### Đọc siêu dữ liệu của trang

`
`bash
ntn API v1/pages/\{page_id}

`

### Đọc trang dưới dạng Markdown (thân thiện với đại lý)

`
`bash
ntn API v1/pages/\{page_id}/markdown

`

### Đọc nội dung trang dưới dạng khối

`
`bash
ntn API v1/blocks/\{page_id}/children

`

### Tạo trang từ Markdown

`
`bash
ntn API v1/pages \
  parent[page_id]=xxx \
  properties[title][0][text][content]="Notes from meeting" \
  markdown="# Agenda
- Q3 roadmap

- Hiring"

`

### Vá một trang bằng Markdown

`
``` bash
ntn API v1/pages/\{page_id}/markdown -X PATCH \
  markdown="## Update

Shipped the prototype."

`

### Truy vấn cơ sở dữ liệu (nguồn dữ liệu)

`
`bash
ntn API v1/data_sources/\{data_source_id}/query -X POST \
  filter[property]=Status filter[select][equals]=Active

`
``Đối với các truy vấn phức tạp với 
`sorts

, nhiều mệnh đề bộ lọc hoặc logic phức hợp, hãy đặt JSON vào:

`
`bash
echo '\{"filter": \{"property": "Status", "select": \{"equals": "Active"}}, "sorts": [\{"property": "Date", "direction": "descending"}]}' | \
  ntn API v1/data_sources/\{data_source_id}/query -X POST --JSON -

`

### Tải lên tệp (một dòng - chiến thắng CLI lớn nhất)

`
`bash
ntn files create < photo.png
ntn files create --external-url https://example.com/photo.png
ntn files list

`
``So sánh với luồng HTTP 3 bước (tạo tải lên → byte PUT → tham chiếu).

### Các biến env hữu ích
| Var | Hiệu ứng |
|---|---|
| 
`NOTION_API_TOKEN
` | Mã thông báo xác thực (ghi đè chuỗi khóa) - đặt mã này thành mã thông báo tích hợp của bạn |
| 
`NOTION_KEYRING=0
` | Tín dụng dựa trên tệp tại 

~/.config/notion/auth.JSON
` thay vì chuỗi khóa hệ điều hành |
| 
`NOTION_WORKSPACE_ID
` | Bỏ qua lời nhắc chọn không gian làm việc |

## Đường dẫn B - HTTP + Curl (đa nền tảng, mặc định trên Windows)

Tất cả các yêu cầu đều có chung mẫu này:

`bash
curl -s -X GET "https://API.notion.com/v1/..." \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON"

`
``Trên Windows, 
`curl
` đi kèm với Windows 10+ hoạt động bình thường. Người dùng PowerShell cũng có thể sử dụng 
`Invoke-RestMethod

.

### Tìm kiếm

`
``` bash
curl -s -X POST "https://API.notion.com/v1/search" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '\{"query": "page title"}'

`

### Đọc siêu dữ liệu của trang

`
``` bash
curl -s "https://API.notion.com/v1/pages/\{page_id}" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

`

### Đọc trang dưới dạng Markdown (thân thiện với đại lý)

Dễ dàng cung cấp dữ liệu cho mô hình hơn là chặn JSON.

``` bash
curl -s "https://API.notion.com/v1/pages/\{page_id}/markdown" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

`

### Đọc nội dung trang dưới dạng khối (khi bạn cần cấu trúc)

`
``` bash
curl -s "https://API.notion.com/v1/blocks/\{page_id}/children" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

`

### Tạo trang từ Markdown``POST /v1/pages
` chấp nhận thông số nội dung 
`markdown

.

``` bash
curl -s -X POST "https://API.notion.com/v1/pages" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '{
    "parent": \{"page_id": "xxx"},
    "properties": \{"title": [\{"text": \{"content": "Notes from meeting"}}]},
    "markdown": "# Agenda\n\n- Q3 roadmap\n- Hiring\n\n## Decisions\n- Ship MVP Friday"
  }'

`

### Vá một trang bằng Markdown

`
``` bash
curl -s -X PATCH "https://API.notion.com/v1/pages/\{page_id}/markdown" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '\{"markdown": "## Update\n\nShipped the prototype."}'

`

### Tạo trang trong cơ sở dữ liệu (thuộc tính đã nhập)

`
``` bash
curl -s -X POST "https://API.notion.com/v1/pages" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '{
    "parent": \{"database_id": "xxx"},
    "properties": {
      "Name": \{"title": [\{"text": \{"content": "New Item"}}]},
      "Status": \{"select": \{"name": "Todo"}}
    }
  }'

`

### Truy vấn cơ sở dữ liệu (nguồn dữ liệu)

`
``` bash
curl -s -X POST "https://API.notion.com/v1/data_sources/\{data_source_id}/query" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '{
    "filter": \{"property": "Status", "select": \{"equals": "Active"}},
    "sorts": [\{"property": "Date", "direction": "descending"}]
  }'

`

### Tạo cơ sở dữ liệu

`
``` bash
curl -s -X POST "https://API.notion.com/v1/data_sources" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '{
    "parent": \{"page_id": "xxx"},
    "title": [\{"text": \{"content": "My Database"}}],
    "properties": {
      "Name": \{"title": \{}},
      "Status": \{"select": \{"options": [\{"name": "Todo"}, \{"name": "Done"}]}},
      "Date": \{"date": \{}}
    }
  }'

`

### Cập nhật thuộc tính trang

`
``` bash
curl -s -X PATCH "https://API.notion.com/v1/pages/\{page_id}" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '\{"properties": \{"Status": \{"select": \{"name": "Done"}}}}'

`

### Nối các khối vào một trang

`
``` bash
curl -s -X PATCH "https://API.notion.com/v1/blocks/\{page_id}/children" \

  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '{
    "children": [
      \{"object": "block", "type": "paragraph", "paragraph": \{"rich_text": [\{"text": \{"content": "Hello from Hermes!"}}]}}
    ]
  }'

`

### Tải tệp lên (quy trình 3 bước)

`
``` bash

# 1. Create upload
curl -s -X POST "https://API.notion.com/v1/file_uploads" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/JSON" \
  -d '\{"filename": "photo.png", "content_type": "image/png"}'

# 2. PUT bytes to the upload_url returned above
curl -s -X PUT "\{upload_url}" --data-binary @photo.png

# 3. Reference \{file_upload_id} in a page/block payload

`

## Loại thuộc tính

Các định dạng thuộc tính chung cho các mục cơ sở dữ liệu:
- **Tiêu đề:** 

\{"title": [\{"text": \{"content": "..."}}]}

- **Văn bản có định dạng:** 

\{"rich_text": [\{"text": \{"content": "..."}}]}

- **Chọn:** 

\{"select": \{"name": "Option"}}

- **Chọn nhiều:** 

\{"multi_select": [\{"name": "A"}, \{"name": "B"}]}

- **Ngày:** 

\{"date": \{"start": "2026-01-15", "end": "2026-01-16"}}

- **Hộp kiểm:** 

\{"checkbox": true}

- **Số:** 

\{"number": 42}

- **URL:** 

\{"url": "https://..."}

- **Email:** 

\{"email": "user@example.com"}

- **Liên quan:** 

\{"relation": [\{"id": "page_id"}]}

## Phiên bản API 2025-09-03 — Cơ sở dữ liệu và Nguồn dữ liệu
- **Cơ sở dữ liệu trở thành nguồn dữ liệu.** Sử dụng điểm cuối 

/data_sources/
` để truy vấn và truy xuất.
- **Hai ID cho mỗi cơ sở dữ liệu:** 
`database_id
` và 
`data_source_id

.
  - 
`database_id
` khi tạo trang: 
`parent: \{"database_id": "..."}

  - 
`data_source_id
` khi truy vấn: 
`POST /v1/data_sources/\{id}/query

- Tìm kiếm trả về cơ sở dữ liệu dạng 

"object": "data_source"
` với trường 
`data_source_id

.

## Notion Workers (nâng cao, yêu cầu 
`ntn

)

Công nhân là các chương trình TypeScript lưu trữ Notion cho bạn. Một công nhân có thể tiếp xúc với bất kỳ sự kết hợp nào của:
- **Đồng bộ hóa** — kéo dữ liệu từ các API bên ngoài vào cơ sở dữ liệu Notion theo lịch trình (mặc định là 30 phút).
- **Công cụ** — xuất hiện dưới dạng công cụ có thể gọi được bên trong Tác nhân tùy chỉnh của Notion.
- **Webhooks** — nhận các sự kiện HTTP từ các dịch vụ bên ngoài (GitHub, Stripe, v.v.) và hoạt động trong Notion.

**Gating kế hoạch / nền tảng:**
- CLI hoạt động trên mọi kế hoạch. **Việc triển khai Công nhân cần có Doanh nghiệp hoặc Doanh nghiệp.**
- 
`ntn
` chỉ dành cho macOS/Linux kể từ tháng 5 năm 2026. Người dùng Windows cần WSL2 hoặc chờ hỗ trợ riêng.
- Miễn phí đến hết ngày 11 tháng 8 năm 2026; được đo lường trên các khoản tín dụng Notion sau đó.

### Công nhân tối thiểu

``` bash
ntn workers new my-worker      # scaffold
cd my-worker

# Edit src/index.ts
ntn workers deploy --name my-worker

`
```src/index.ts

:

`
`TypeScript
 import { Worker } from "@notionhq/workers";`const worker = new Worker();
 export default worker;`worker.tool("greet", {
  title: "Greet a User",
  description: "Returns a friendly greeting",
  inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
  execute: async ({ name }) => 
`Hello, $\{name}!

,
});

`

### Khả năng Webhook

`TypeScript
worker.webhook("onGitHubPush", {
  title: "GitHub Push Handler",
  execute: async (events, { notion }) => {
    for (const event of events) {
      // event.body, event.rawBody (for signature verification), event.headers
      console.log("got delivery", event.deliveryId);
    }
  },
});

`
``Sau khi triển khai: 
`ntn workers webhooks list
` hiển thị URL Notion tạo ra. Hãy coi URL đó là bí mật — bất kỳ ai có URL đó đều có thể ĐĂNG sự kiện trừ khi bạn thêm xác minh chữ ký.

### Lệnh vòng đời của Worker

``` bash
ntn workers deploy
ntn workers list
ntn workers exec <capability-key -d '\{"name": "world"}'
ntn workers sync trigger <key            # run a sync now
ntn workers sync pause <key
ntn workers env set GitHub_WEBHOOK_SECRET=...
ntn workers runs list                     # recent invocations
ntn workers runs logs <run-id
ntn workers webhooks list

`
``Khi được yêu cầu xây dựng Công nhân, giàn giáo bằng 
`ntn workers new

, hãy viết mã trong 
`src/index.ts

, đặt bất kỳ bí mật nào với 
`ntn workers env set
` và triển khai. Tài liệu của Notion tại https://developers.notion.com/workers bao gồm toàn bộ bề mặt API.

## Đánh dấu theo hương vị Notion (được sử dụng bởi các điểm cuối 

/markdown

)

CommonMark tiêu chuẩn cộng với các thẻ giống XML dành cho các khối dành riêng cho Notion. Sử dụng **tab** để thụt lề.

**Các khối ngoài CommonMark:**

`

<callout icon="🎯" color="blue_bg"
	Ship the MVP by **Friday**.
&lt;/callout`<details color="gray">
&lt;summaryToggle title&lt;/summary
	Children indented one tab
&lt;/details`&lt;columns
	&lt;columnLeft side&lt;/column
	&lt;columnRight side&lt;/column
&lt;/columns`&lt;table_of_contents color="gray"/

`
``**Nội tuyến:**

- Đề cập: 

&lt;mention-user url="..."/

, 

&lt;mention-page url="..."Title&lt;/mention-page

, 

&lt;mention-date start="2026-05-15"/

- Gạch chân: 

<span underline="true">text&lt;/span

- Màu sắc: 

<span color="blue">text&lt;/span
` hoặc 

\&#123;color="blue"&#125;
` cấp khối trên dòng đầu tiên
- Toán: 

$x^2$
` nội tuyến, khối 

$$ ... $$

- Trích dẫn: 

[^https://example.com]
``**Màu sắc:** 
`gray brown orange yellow green blue purple pink red

, cùng với các biến thể 

*_bg
` dành cho nền.

Tiêu đề 5/6 thu gọn thành H4. Nhiều dòng 

>
` hiển thị dưới dạng các khối trích dẫn riêng biệt — sử dụng 

&lt;br
` bên trong một 

>
` duy nhất cho các trích dẫn nhiều dòng.

## Chọn con đường đúng

| Nhiệm vụ | mac / Linux | Windows |
|---|---|---|
| Đọc/ghi trang, tìm kiếm, truy vấn cơ sở dữ liệu |

ntn API ...
` | cuộn tròn |
| Đọc một trang để đại lý tóm tắt |

ntn API v1/pages/\&#123;id&#125;/markdown
` | điểm cuối 

/markdown
` |
| Tải lên một tập tin |

ntn files create &lt; file
` | Luồng HTTP 3 bước |
| Khám phá API một lần |

ntn API ...
` | cuộn tròn |
| Xây dựng công cụ đồng bộ hóa/webhook/đại lý được lưu trữ bởi Notion |

ntn workers ...
` | WSL2 + 
`ntn workers ...
` |

## Ghi chú
- ID trang/cơ sở dữ liệu là UUID (có hoặc không có dấu gạch ngang - cả hai đều được chấp nhận).
- Giới hạn tốc độ: trung bình ~3 yêu cầu/giây. CLI không bỏ qua điều này.
- API không thể đặt bộ lọc **chế độ xem** cơ sở dữ liệu — đó chỉ dành cho giao diện người dùng.
- Sử dụng 

"is_inline": true
` khi tạo nguồn dữ liệu để nhúng vào một trang.
- Luôn chuyển 

-s
` để cuộn tròn nhằm chặn các thanh tiến trình (đầu ra tác nhân sạch hơn).
- Truyền JSON qua 
`jq
` khi đọc: 

... | jq '.results[0].properties'

.
- Notion hiện cũng cung cấp một máy chủ MCP (
`Notion MCP

, hiệu quả sử dụng mã thông báo trên các hoạt động DB cao hơn ~91% so với phiên bản trước) — kết nối nó thông qua hỗ trợ MCP của Hermes nếu bạn muốn truy cập Notion trực tuyến từ bên trong một phiên, nhưng các đường dẫn trên là đủ cho hầu hết các tác vụ một lần.