# Notion

> Notion API — create, read, search pages, databases, and blocks Use when this capability is needed.

- Skill: `tomevault-io/notion-15` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/notion-15`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/notion-15/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/notion-15

---

# Notion

Manage Notion pages, databases, and blocks via the REST API.

## Setup

1. **Check existing credentials:**
   ```
   vault_get notion_api_key
   ```

2. **If not configured:**
   - Go to https://www.notion.so/my-integrations and create an integration
   - Copy the API key (starts with `ntn_` or `secret_`)
   - Save to vault:
     ```
     vault_save notion_api_key "ntn-your-key-here"
     ```
   The key is auto-injected as `$NOTION_API_KEY`.
   - **Important:** Share target pages/databases with your integration (click "..." → "Connect to" → integration name)

## API Basics

All requests need these headers:

```bash
curl -s "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"
```

## Search pages and databases

```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": "SEARCH_TERM"}' | jq '.results[] | {id, object: .object, title: (.properties.title.title[0].plain_text // .title[0].plain_text // "untitled")}'
```

## Read a page

```bash
# Page properties
curl -s "https://api.notion.com/v1/pages/PAGE_ID" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" | jq '.properties'

# 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" | jq '.results[] | {type, text: (.paragraph.rich_text[0].plain_text // .heading_1.rich_text[0].plain_text // .to_do.rich_text[0].plain_text // null)}'
```

## Create a page

```bash
# 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": "DATABASE_ID"},
    "properties": {
      "Name": {"title": [{"text": {"content": "Task title"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }' | jq '{id, url}'

# Under another page
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": "PARENT_PAGE_ID"},
    "properties": {
      "title": [{"text": {"content": "New Page Title"}}]
    },
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Page content here."}}]}}
    ]
  }' | jq '{id, url}'
```

## Query a database

```bash
curl -s -X POST "https://api.notion.com/v1/databases/DATABASE_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": "In Progress"}},
    "sorts": [{"property": "Created", "direction": "descending"}]
  }' | jq '.results[] | {id, title: .properties.Name.title[0].plain_text, status: .properties.Status.select.name}'
```

## 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": "to_do", "to_do": {"rich_text": [{"text": {"content": "New task item"}}], "checked": false}}
    ]
  }'
```

## Tips

- The `Notion-Version` header is required — use `2025-09-03` (latest).
- Database IDs and page IDs can be found in the URL: `notion.so/workspace/PAGE_ID`.
- Always search first to find the right page/database before creating new ones.
- The integration only sees pages that have been explicitly shared with it.
- For complex queries, use filters and sorts to narrow results.

## Triggers

notion, add to notion, notion page, notion database, notion task, create page, search notion,
adicionar no notion, buscar no notion, criar página

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jholhewres) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->