Notion

Skill braxtonROSE4/zorro-agent/skills/productivity/notion

The Agent that evolves through use, distills session experience into domain knowledge, then converts knowledge into executable skills.

Install

npx -y skills add braxtonROSE4/zorro-agent --skill notion

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

7 stars7 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Notion API for creating and managing pages, databases, and blocks via curl. Search, create, update, and query Notion workspaces directly from the terminal.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

5.2 KB, as published. Nobody here has run it

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

Create an integration at https://notion.so/my-integrations
Copy the API key (starts with ntn_ or secret_)
Store it in ~/.zorro/.env:
```
NOTION_API_KEY=ntn_your_key_here
```
Important: Share target pages/databases with your integration in Notion (click "..." → "Connect to" → your integration name)

API Basics

All requests use this pattern:

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

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

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)

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

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

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

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

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

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

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": "[email protected]"}
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 Zorro)
Pipe output through jq for readable JSON: ... | jq '.results[0].properties'