SkillbundledHermes Bundled Skills

Notion

Name: Notion
Author: community

Notion: مهارة ينشرها مجتمع Hermes. مجالها قراءة قواعد البيانات والاستعلام عنها. الرخصة MIT. الإصدار الموثّق 2.0.0. مثبّتة افتراضيًا مع Hermes، فلا تحتاج خطوة تثبيت. تدعم: linux، macos، windows.

NotionProductivityNotesDatabaseAPICLIWorkersBundled

آخر تحقق من السجل2026-08-18v2.0.0community

افتح المصدر الأصلي ↗Read in English

المعنى ببساطة

ماذا يضيف إلى Hermes؟

Notion هي مهارة مرتبطة بمجال قواعد البيانات والبيانات. يمنح الوكيل طريقة منظمة لقراءة البيانات أو الاستعلام عنها. بعض الأدوات قد تسمح بالكتابة أيضًا، لذلك تحتاج إلى حدود واضحة.

هذا تفسير مبسّط مبني على وصف الناشر. أبقينا الوصف الإنجليزي بجانبه حتى تستطيع مقارنة المعنى بالمصدر.

استخدمه عندما

استخدمه عندما يكون هدفك واضحًا في قواعد البيانات والبيانات وتستطيع تحديد البيانات والأفعال التي يحتاجها فقط.

لا تحتاجه عندما

لا تضفه لمجرد التجربة إذا كان لديك طريق أبسط داخل Hermes، أو إذا لم تستطع مراجعة المصدر والصلاحيات.

لمن يناسب؟

مناسب لمن يريد طريقة عمل قابلة للتكرار داخل Hermes.

أول اختبار آمن

استخدم قاعدة بيانات تجريبية وحساب قراءة فقط، ثم اطلب استعلامًا بسيطًا لا يغيّر أي سجل.

الوصف الأصلي من الناشر، من دون ترجمة تغيّر المعنى

Notion API + ntn CLI: pages, databases, markdown, Workers

✓

مصدر البيانات

فُهرس هذا الإدخال من Hermes Bundled Skills. الشرح العربي يفسّر النوع والمجال ولا يضيف وظيفة غير مذكورة في المصدر.

مراجعة الأمان

المصدر رسمي أو خضع لمراجعة تحريرية، لكن ذلك لا يغني عن مراجعة الصلاحيات والإصدار.

مسار تثبيت آمن

افحص، ثبّت، ثم اختبر.

01
افتح المصدر
طابق اسم الناشر والرخصة والوصف مع حاجتك، وراجع آخر تحديث فعلي.
02
راجع الصلاحيات والأسرار
لا تلصق قيمة سر داخل الموقع. استخدم أسماء متغيرات البيئة وامنح أقل نطاق ممكن.
03
انسخ الإعداد فقط بعد المراجعة
الأزرار أدناه تنسخ نصًا إلى الحافظة ولا تشغّل أمرًا على جهازك.
04
اختبر بمهمة غير حساسة
تحقق من الأدوات الظاهرة، ثم استبعد أدوات الكتابة أو الحذف التي لا تحتاجها.

طريقة الإعداد

مثبّتة مسبقًا مع Hermes.

تأتي هذه المهارة مع Hermes وتُحمَّل عندما يرى الوكيل أنها مناسبة. لا شيء لتثبيته؛ اقرأ التعريف أدناه لتعرف ما ستفعله.

افتح الصفحة الرسمية ↗

تعريف المهارة كاملًا

ما الذي يحمّله Hermes بالضبط عند تشغيل هذه المهارة.

منقول من التوثيق الرسمي. اقرأه قبل تفعيل المهارة، فهذا النص يصبح تعليمات الوكيل نفسه.

Notion API + ntn CLI: pages, databases, markdown, Workers.

Skill metadata

جدول مرجعي. لا تقرأه كله، ابحث عن السطر الذي يخصّك فقط.

Source	Bundled (installed by default)
Path	`skills/productivity/notion`
Version	`2.0.0`
Author	community
License	MIT
Platforms	linux, macos, windows
Tags	`Notion`, `Productivity`, `Notes`, `Database`, `API`, `CLI`, `Workers`

Reference: full SKILL.md

شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه.

Talk to Notion two ways. Same integration token works for both — pick by what's available.

◆ ntn CLI — Notion's official CLI. Shorter syntax, one-line file uploads, required for Workers. macOS + Linux only as of May 2026 (Windows support "coming soon"). Default when installed. ◆ HTTP + curl — works everywhere including Windows. Default fallback when ntn isn't installed.

Setup

خطوات عملية بالترتيب. نفّذ خطوة وتأكد أنها نجحت قبل الانتقال للتالية.

1. Get an integration token (required for both paths)

Create an integration at https://notion.so/my-integrations
Copy the API key (starts with ntn_ or secret_)
Store in ${HERMES_HOME:-~/.hermes}/.env:

Textسطر واحد

   NOTION_API_KEY=ntn_your_key_here

Share target pages/databases with the integration in Notion: page menu ... → Connect to → your integration name. Without this, the API returns 404 for that page even though it exists.

2. Install `ntn` (preferred path on macOS / Linux)

Shell7 أسطر

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

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

ntn --version    # verify

Skip ntn login — use the integration token instead. This works headlessly, no browser needed:

Shellسطران

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

Add those exports to your shell profile (or to ${HERMES_HOME:-~/.hermes}/.env) so every session inherits them.

3. Choose path at runtime

Shell5 أسطر

if command -v ntn >/dev/null 2>&1; then
  # use ntn
else
  # fall back to curl
fi

Windows users: skip step 2 entirely until native ntn ships — Path B works fine. If you want CLI ergonomics now, install ntn inside WSL2.

API Basics

شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه.

Notion-Version: 2025-09-03 is required on all HTTP requests. ntn handles this for you. In this version, what users call "databases" are called data sources in the API.

Path A — `ntn` CLI (preferred, macOS / Linux)

شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه.

Raw API calls (shorthand for curl)

Shell4 أسطر

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)

Syntax notes:

key=value — string fields
key[nested]=value — nested object fields
key:=value — typed assignment (booleans, numbers, null, arrays)

Search

Shellسطر واحد

ntn api v1/search query="page title"

Read page metadata

Shellسطر واحد

ntn api v1/pages/{page_id}

Read page as Markdown (agent-friendly)

Shellسطر واحد

ntn api v1/pages/{page_id}/markdown

Read page content as blocks

Shellسطر واحد

ntn api v1/blocks/{page_id}/children

Create page from Markdown

Shell7 أسطر

ntn api v1/pages \
  parent[page_id]=xxx \
  properties[title][0][text][content]="Notes from meeting" \
  markdown="# Agenda

- Q3 roadmap
- Hiring"

Patch a page with Markdown

Shell4 أسطر

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

Shipped the prototype."

Query a database (data source)

Shellسطران

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

For complex queries with sorts, multiple filter clauses, or compound logic, pipe JSON in:

Shellسطران

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

File uploads (one-liner — biggest CLI win)

Shell3 أسطر

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

Compare to the 3-step HTTP flow (create upload → PUT bytes → reference).

Useful env vars

Var	Effect
`NOTION_API_TOKEN`	Auth token (overrides keychain) — set this to your integration token
`NOTION_KEYRING=0`	File-based creds at `~/.config/notion/auth.json` instead of OS keychain
`NOTION_WORKSPACE_ID`	Skip the workspace picker prompt

Path B — HTTP + curl (cross-platform, default on Windows)

إعدادات تضبطها مرة وتنساها. غيّر واحدًا في كل مرة حتى تعرف أثر كل تغيير. تضبط NOTION_API_KEY خارج المحادثة، في بيئة التشغيل.

All requests share this pattern:

Shell4 أسطر

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"

On Windows the curl shipped with Windows 10+ works as-is. PowerShell users can also use Invoke-RestMethod.

Search

Shell5 أسطر

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"}'

Read page metadata

Shell3 أسطر

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

Read page as Markdown (agent-friendly)

Easier to feed to a model than block JSON.

Shell3 أسطر

curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

Read page content as blocks (when you need structure)

Shell3 أسطر

curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

Create page from Markdown

POST /v1/pages accepts a markdown body param.

Shell9 أسطر

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"
  }'

Patch a page with Markdown

Shell5 أسطر

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."}'

Create page in a database (typed properties)

Shell11 سطرًا

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"}}
    }
  }'

Query a database (data source)

Shell8 أسطر

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"}]
  }'

Create a database

Shell13 سطرًا

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": {}}
    }
  }'

Update page properties

Shell5 أسطر

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"}}}}'

Append blocks to a page

Shell9 أسطر

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!"}}]}}
    ]
  }'

File uploads (3-step flow)

Shell11 سطرًا

# 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

Property Types

شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه.

Common property formats for database items:

Title: {"title": [{"text": {"content": "..."}}]}
Rich text: {"rich_text": [{"text": {"content": "..."}}]}
Select: {"select": {"name": "Option"}}
Multi-select: {"multi_select": [{"name": "A"}, {"name": "B"}]}
Date: {"date": {"start": "2026-01-15", "end": "2026-01-16"}}
Checkbox: {"checkbox": true}
Number: {"number": 42}
URL: {"url": "https://..."}
Email: {"email": "user@example.com"}
Relation: {"relation": [{"id": "page_id"}]}

API Version 2025-09-03 — Databases vs Data Sources

شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه.

Databases became data sources. Use /data_sources/ endpoints for queries and retrieval.
Two IDs per database: database_id and data_source_id.
database_id when creating pages: parent: {"database_id": "..."}
data_source_id when querying: POST /v1/data_sources/{id}/query
Search returns databases as "object": "data_source" with the data_source_id field.

Notion Workers (advanced, requires `ntn`)

إعدادات تضبطها مرة وتنساها. غيّر واحدًا في كل مرة حتى تعرف أثر كل تغيير. تضبط GITHUB_WEBHOOK_SECRET خارج المحادثة، في بيئة التشغيل.

Workers are TypeScript programs Notion hosts for you. One worker can expose any combination of:

Syncs — pull data from external APIs into a Notion database on a schedule (default 30 min).
Tools — appear as callable tools inside Notion's Custom Agents.
Webhooks — receive HTTP events from external services (GitHub, Stripe, etc.) and act in Notion.

Plan / platform gating:

CLI works on all plans. Deploying Workers requires Business or Enterprise.
ntn is macOS/Linux only as of May 2026. Windows users need WSL2 or to wait for native support.
Free through August 11, 2026; metered on Notion credits after.

Minimal Worker

Shell4 أسطر

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

src/index.ts:

TypeScript10 أسطر



const worker = new 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}!`,
});

Webhook capability

TypeScript9 أسطر

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);
    }
  },
});

After deploy: ntn workers webhooks list shows the URL Notion generates. Treat that URL as a secret — anyone with it can POST events unless you add signature verification.

Worker lifecycle commands

Shell9 أسطر

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

When asked to build a Worker, scaffold with ntn workers new, write the code in src/index.ts, set any secrets with ntn workers env set, and deploy. Notion's docs at https://developers.notion.com/workers cover the full API surface.

Notion-Flavored Markdown (used by `/markdown` endpoints)

شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه.

Standard CommonMark plus XML-like tags for Notion-specific blocks. Use tabs for indentation.

Blocks beyond CommonMark:

Text15 سطرًا

<callout icon="🎯" color="blue_bg">
	Ship the MVP by **Friday**.
</callout>

<details color="gray">
<summary>Toggle title</summary>
	Children indented one tab
</details>

<columns>
	<column>Left side</column>
	<column>Right side</column>
</columns>

<table_of_contents color="gray"/>

Inline:

Mentions: <mention-user url="..."/>, <mention-page url="...">Title</mention-page>, <mention-date start="2026-05-15"/>
Underline: text
Color: text or block-level {color="blue"} on the first line
Math: inline $x^2$ , block $$ ... $$
Citations: [^https://example.com]

Colors: gray brown orange yellow green blue purple pink red, plus *_bg variants for backgrounds.

Headings 5/6 collapse to H4. Multiple > lines render as separate quote blocks — use   inside a single > for multi-line quotes.

Choosing the Right Path

جدول مرجعي. لا تقرأه كله، ابحث عن السطر الذي يخصّك فقط.

Task	mac / Linux	Windows
Read/write pages, search, query databases	`ntn api ...`	curl
Read a page for an agent to summarize	`ntn api v1/pages/{id}/markdown`	curl `/markdown` endpoint
Upload a file	`ntn files create < file`	3-step HTTP flow
One-off API exploration	`ntn api ...`	curl
Build a sync / webhook / agent tool hosted by Notion	`ntn workers ...`	WSL2 + `ntn workers ...`

Notes

شرح للفكرة نفسها. اقرأه ببطء، فبقية الأقسام تبني عليه.

Page/database IDs are UUIDs (with or without dashes — both accepted).
Rate limit: ~3 requests/second average. The CLI doesn't bypass this.
The API cannot set database view filters — that's UI-only.
Use "is_inline": true when creating data sources to embed them in a page.
Always pass -s to curl to suppress progress bars (cleaner agent output).
Pipe JSON through jq when reading: ... | jq '.results[0].properties'.
Notion also ships an MCP server now (Notion MCP, ~91% more token-efficient on DB ops than the previous version) — wire it via Hermes' MCP support if you want streaming Notion access from inside a session, but the paths above are enough for most one-shot tasks.

Notion

ماذا يضيف إلى Hermes؟

افحص، ثبّت، ثم اختبر.

مثبّتة مسبقًا مع Hermes.

ما الذي يحمّله Hermes بالضبط عند تشغيل هذه المهارة.

1. Get an integration token (required for both paths)

2. Install ntn (preferred path on macOS / Linux)

3. Choose path at runtime

Raw API calls (shorthand for curl)

Search

Read page metadata

Read page as Markdown (agent-friendly)

Read page content as blocks

Create page from Markdown

Patch a page with Markdown

Query a database (data source)

File uploads (one-liner — biggest CLI win)

Useful env vars

Search

Read page metadata

Read page as Markdown (agent-friendly)

Read page content as blocks (when you need structure)

Create page from Markdown

Patch a page with Markdown

Create page in a database (typed properties)

Query a database (data source)

Create a database

Update page properties

Append blocks to a page

File uploads (3-step flow)

Minimal Worker

Webhook capability

Worker lifecycle commands

2. Install `ntn` (preferred path on macOS / Linux)