Sync all skills and memories 2026-04-14 07:27
This commit is contained in:
171
skills/productivity/notion/SKILL.md
Normal file
171
skills/productivity/notion/SKILL.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
name: notion
|
||||
description: Notion API for creating and managing pages, databases, and blocks via curl. Search, create, update, and query Notion workspaces directly from the terminal.
|
||||
version: 1.0.0
|
||||
author: community
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Notion, Productivity, Notes, Database, API]
|
||||
homepage: https://developers.notion.com
|
||||
prerequisites:
|
||||
env_vars: [NOTION_API_KEY]
|
||||
---
|
||||
|
||||
# Notion API
|
||||
|
||||
Use the Notion API via curl to create, read, update pages, databases (data sources), and blocks. No extra tools needed — just curl and a Notion API key.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Create an integration at https://notion.so/my-integrations
|
||||
2. Copy the API key (starts with `ntn_` or `secret_`)
|
||||
3. Store it in `~/.hermes/.env`:
|
||||
```
|
||||
NOTION_API_KEY=ntn_your_key_here
|
||||
```
|
||||
4. **Important:** Share target pages/databases with your integration in Notion (click "..." → "Connect to" → your integration name)
|
||||
|
||||
## API Basics
|
||||
|
||||
All requests use this pattern:
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
The `Notion-Version` header is required. This skill uses `2025-09-03` (latest). In this version, databases are called "data sources" in the API.
|
||||
|
||||
## Common Operations
|
||||
|
||||
### Search
|
||||
|
||||
```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"}'
|
||||
```
|
||||
|
||||
### Get Page
|
||||
|
||||
```bash
|
||||
curl -s "https://api.notion.com/v1/pages/{page_id}" \
|
||||
-H "Authorization: Bearer $NOTION_API_KEY" \
|
||||
-H "Notion-Version: 2025-09-03"
|
||||
```
|
||||
|
||||
### Get Page Content (blocks)
|
||||
|
||||
```bash
|
||||
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 in a Database
|
||||
|
||||
```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"}}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Query a Database
|
||||
|
||||
```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"}]
|
||||
}'
|
||||
```
|
||||
|
||||
### Create a Database
|
||||
|
||||
```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": {}}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Update Page Properties
|
||||
|
||||
```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"}}}}'
|
||||
```
|
||||
|
||||
### Add Content to a Page
|
||||
|
||||
```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!"}}]}}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## 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"}]}`
|
||||
|
||||
## Key Differences in API Version 2025-09-03
|
||||
|
||||
- **Databases → Data Sources:** Use `/data_sources/` endpoints for queries and retrieval
|
||||
- **Two IDs:** Each database has both a `database_id` and a `data_source_id`
|
||||
- Use `database_id` when creating pages (`parent: {"database_id": "..."}`)
|
||||
- Use `data_source_id` when querying (`POST /v1/data_sources/{id}/query`)
|
||||
- **Search results:** Databases return as `"object": "data_source"` with their `data_source_id`
|
||||
|
||||
## Notes
|
||||
|
||||
- Page/database IDs are UUIDs (with or without dashes)
|
||||
- Rate limit: ~3 requests/second average
|
||||
- The API cannot set database view filters — that's UI-only
|
||||
- Use `is_inline: true` when creating data sources to embed them in pages
|
||||
- Add `-s` flag to curl to suppress progress bars (cleaner output for Hermes)
|
||||
- Pipe output through `jq` for readable JSON: `... | jq '.results[0].properties'`
|
||||
112
skills/productivity/notion/references/block-types.md
Normal file
112
skills/productivity/notion/references/block-types.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Notion Block Types
|
||||
|
||||
Reference for creating and reading all common Notion block types via the API.
|
||||
|
||||
## Creating blocks
|
||||
|
||||
Use `PATCH /v1/blocks/{page_id}/children` with a `children` array. Each block follows this structure:
|
||||
|
||||
```json
|
||||
{"object": "block", "type": "<type>", "<type>": { ... }}
|
||||
```
|
||||
|
||||
### Paragraph
|
||||
|
||||
```json
|
||||
{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello world"}}]}}
|
||||
```
|
||||
|
||||
### Headings
|
||||
|
||||
```json
|
||||
{"type": "heading_1", "heading_1": {"rich_text": [{"text": {"content": "Title"}}]}}
|
||||
{"type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Section"}}]}}
|
||||
{"type": "heading_3", "heading_3": {"rich_text": [{"text": {"content": "Subsection"}}]}}
|
||||
```
|
||||
|
||||
### Bulleted list
|
||||
|
||||
```json
|
||||
{"type": "bulleted_list_item", "bulleted_list_item": {"rich_text": [{"text": {"content": "Item"}}]}}
|
||||
```
|
||||
|
||||
### Numbered list
|
||||
|
||||
```json
|
||||
{"type": "numbered_list_item", "numbered_list_item": {"rich_text": [{"text": {"content": "Step 1"}}]}}
|
||||
```
|
||||
|
||||
### To-do / checkbox
|
||||
|
||||
```json
|
||||
{"type": "to_do", "to_do": {"rich_text": [{"text": {"content": "Task"}}], "checked": false}}
|
||||
```
|
||||
|
||||
### Quote
|
||||
|
||||
```json
|
||||
{"type": "quote", "quote": {"rich_text": [{"text": {"content": "Something wise"}}]}}
|
||||
```
|
||||
|
||||
### Callout
|
||||
|
||||
```json
|
||||
{"type": "callout", "callout": {"rich_text": [{"text": {"content": "Important note"}}], "icon": {"emoji": "💡"}}}
|
||||
```
|
||||
|
||||
### Code
|
||||
|
||||
```json
|
||||
{"type": "code", "code": {"rich_text": [{"text": {"content": "print('hello')"}}], "language": "python"}}
|
||||
```
|
||||
|
||||
### Toggle
|
||||
|
||||
```json
|
||||
{"type": "toggle", "toggle": {"rich_text": [{"text": {"content": "Click to expand"}}]}}
|
||||
```
|
||||
|
||||
### Divider
|
||||
|
||||
```json
|
||||
{"type": "divider", "divider": {}}
|
||||
```
|
||||
|
||||
### Bookmark
|
||||
|
||||
```json
|
||||
{"type": "bookmark", "bookmark": {"url": "https://example.com"}}
|
||||
```
|
||||
|
||||
### Image (external URL)
|
||||
|
||||
```json
|
||||
{"type": "image", "image": {"type": "external", "external": {"url": "https://example.com/photo.png"}}}
|
||||
```
|
||||
|
||||
## Reading blocks
|
||||
|
||||
When reading blocks from `GET /v1/blocks/{page_id}/children`, each block has a `type` field. Extract readable text like this:
|
||||
|
||||
| Type | Text location | Extra fields |
|
||||
|------|--------------|--------------|
|
||||
| `paragraph` | `.paragraph.rich_text` | — |
|
||||
| `heading_1/2/3` | `.heading_N.rich_text` | — |
|
||||
| `bulleted_list_item` | `.bulleted_list_item.rich_text` | — |
|
||||
| `numbered_list_item` | `.numbered_list_item.rich_text` | — |
|
||||
| `to_do` | `.to_do.rich_text` | `.to_do.checked` (bool) |
|
||||
| `toggle` | `.toggle.rich_text` | has children |
|
||||
| `code` | `.code.rich_text` | `.code.language` |
|
||||
| `quote` | `.quote.rich_text` | — |
|
||||
| `callout` | `.callout.rich_text` | `.callout.icon.emoji` |
|
||||
| `divider` | — | — |
|
||||
| `image` | `.image.caption` | `.image.file.url` or `.image.external.url` |
|
||||
| `bookmark` | `.bookmark.caption` | `.bookmark.url` |
|
||||
| `child_page` | — | `.child_page.title` |
|
||||
| `child_database` | — | `.child_database.title` |
|
||||
|
||||
Rich text arrays contain objects with `.plain_text` — concatenate them for readable output.
|
||||
|
||||
---
|
||||
|
||||
*Contributed by [@dogiladeveloper](https://github.com/dogiladeveloper)*
|
||||
Reference in New Issue
Block a user