# Notion Workspace

> Manage Notion workspace: search pages and databases, read markdown, create pages, insert rows, triggers, MCP. Powered by AISA gateway (Notion toolkit). Requires AISA_API_KEY and curl. Keywords: notion, workspace, page, database, block, markdown, wiki, task board, insert row, OAuth. Use when: the user needs web search, research, source discovery, or content extraction.

- Skill: `baofeng-tech/notion-workspace-3` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add baofeng-tech/notion-workspace-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/baofeng-tech/notion-workspace-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: baofeng-tech (https://skillmd.com/u/baofeng-tech)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/baofeng-tech/notion-workspace-3

---


# Notion Workspace (`notion-workspace`)

**Standalone** skill for Notion pages, databases, and workspace automation via AISA. No other skill required.

Covers: OAuth connect, tool discovery/execute, Notion ID rules, triggers, and MCP for Notion only.

## Quick Start

```bash
export AISA_API_KEY="your-key"   # Linux/macOS
# $env:AISA_API_KEY = "your-key"  # Windows PowerShell
```

- **Base URL:** `https://api.aisa.one`
- **Path prefix:** `/apis/v1/composio/...`
- **Toolkit slug:** `notion`
- **Header:** `Authorization: Bearer $AISA_API_KEY`

**Windows:** Use `curl.exe` in PowerShell.

HTTP patterns (session, OAuth, execute, triggers): `references/api_basics.md`

## When to use

- Search, read, or write Notion pages and databases
- Connect a user/workspace to Notion (OAuth or API key)
- Insert or update database rows, append page content, export Markdown
- Notion triggers, webhooks, or Notion-only MCP server

## When NOT to use

- No `AISA_API_KEY` — get one at [aisa.one](https://aisa.one)
- Direct upstream provider endpoints without the AISA gateway
- Official Notion API only (no AISA gateway)
- Other toolkits (GitHub, Slack, Gmail, etc.) — use a different skill

## What Can You Do?

```text
"Connect user alice to Notion via OAuth"
"Search for pages titled Roadmap and export Markdown"
"Add a row to my Tasks database with status In Progress"
"Create a child page under X and append bullet content"
"Set up a trigger when a new row is added to database Y"
```

## Intent → Workflow

| User intent | Read this |
|-------------|-----------|
| API key / session / generic curl | `references/api_basics.md` |
| connect / OAuth / authorize Notion | `references/workflow_connect.md` |
| search / find page or database | `references/workflow_read.md` § Search |
| read markdown / page content / blocks | `references/workflow_read.md` § Content |
| query database / filter rows | `references/workflow_database.md` § Query |
| create page / write content / append blocks | `references/workflow_write_page.md` |
| insert row / update properties | `references/workflow_database.md` § Write |
| comments / file upload | `references/notion_intent_to_tool.md` |
| page updated / trigger / webhook / MCP | `references/notion_triggers.md` |
| errors / 404 / wrong ID type | `references/notion_gotchas.md` |
| non-ASCII / Chinese field names / mojibake | `references/notion_gotchas.md` § 8 |
| which tool slug? | `references/notion_intent_to_tool.md` |

> Unclear intent: `GET auth/session/info`, ensure `connected_account_id` (N1), then ask read vs write.

---

## Core Workflows

### N1 — Connect Notion

1. `GET /auth_configs?toolkit_slug=notion` → `auth_config_id`
2. **Confirm with user** → `POST /connected_accounts/link` with `user_id`
3. User opens `redirect_url` in browser
4. Poll `GET /connected_accounts?user_ids={user_id}&toolkit_slugs=notion` every 3–5s until `ACTIVE` (~2 min max)
5. Save `items[].id` as `connected_account_id`

If `ACTIVE` already exists for same `user_id` + `notion`, reuse it.

Details: `references/workflow_connect.md`

### N2 — Discover and read

1. Resolve `connected_account_id` (N1 if missing)
2. Discover IDs: `NOTION_SEARCH_NOTION_PAGE` or `NOTION_FETCH_DATA`
3. Read page: `NOTION_GET_PAGE_MARKDOWN` or `NOTION_FETCH_BLOCK_CONTENTS`
4. Read database: `NOTION_FETCH_DATABASE` → `NOTION_QUERY_DATABASE` or `NOTION_QUERY_DATABASE_WITH_FILTER`

Details: `references/workflow_read.md`

### N3 — Write pages and blocks

1. Resolve `connected_account_id` (N1 if missing)
2. `GET /tools/{tool_slug}` — **never guess slug**; see `references/notion_intent_to_tool.md`
3. **Confirm with user** before any write
4. Create page: `NOTION_CREATE_NOTION_PAGE` (`parent_id`, `title`) → save returned `id`
5. Add body: `NOTION_ADD_MULTIPLE_PAGE_CONTENT` (`parent_block_id`, `content_blocks[]`)
6. Check `successful` in response; on false read `error`

> Key param: `NOTION_ADD_MULTIPLE_PAGE_CONTENT` uses `parent_block_id` (not `page_id`) and `content_blocks` (not `child_blocks`).

Details: `references/workflow_write_page.md`

### N4 — Database rows

1. **Check sharing**: Confirm the target database (and its parent page chain up to workspace root) is shared with the AISA integration in Notion UI (⋯ → Connections). A 404 on execute almost always means the integration cannot see the resource.
2. **Always** `NOTION_FETCH_DATABASE` first
3. **Confirm with user** → `NOTION_INSERT_ROW_DATABASE` (`properties` as list of `{name, type, value}`)
4. Update: `NOTION_UPDATE_PAGE`; filter: `NOTION_QUERY_DATABASE_WITH_FILTER`

Details: `references/workflow_database.md`

### N5 — Troubleshoot

`references/notion_gotchas.md` + `references/api_basics.md` Troubleshooting table.

---

## Execute pattern (all Notion tools)

```bash
curl -X POST "https://api.aisa.one/apis/v1/composio/tools/execute/NOTION_SEARCH_NOTION_PAGE" \
  -H "Authorization: Bearer $AISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "ca_xxxxxxxx",
    "user_id": "alice@example.com",
    "arguments": { }
  }'
```

Schema: `GET /tools/{tool_slug}` → `input_parameters`.  
List tools: `GET /tools?toolkit_slug=notion&limit=50`

---

## Safety

- **Confirm** before POST that writes to Notion or changes triggers/webhooks/MCP
- Read-only GET/list/search need no confirmation unless user forbids network
- OAuth `redirect_url` must be opened by a human
- Never use mock IDs (`test_nanoid_001`)

---

## Reference routing

| Topic | File |
|-------|------|
| Gateway, OAuth, execute, triggers HTTP | `references/api_basics.md` |
| Notion pitfalls | `references/notion_gotchas.md` |
| Intent → tool_slug | `references/notion_intent_to_tool.md` |
| Connect | `references/workflow_connect.md` |
| Read / search | `references/workflow_read.md` |
| Write pages | `references/workflow_write_page.md` |
| Database | `references/workflow_database.md` |
| Triggers, MCP | `references/notion_triggers.md` |