| name | notion-full-control |
| description | Use when work requires direct, full Notion API access outside the bundled Notion connector, including searching pages and databases, inspecting schemas, querying database rows, creating or updating pages, appending blocks, and sending raw Notion API requests with a locally configured integration token. |
Notion Full Control
Use this skill when the built-in Notion connector is unavailable or insufficient and you need direct Notion API access.
This skill provides a local CLI wrapper around the Notion API with:
- secure token lookup from macOS Keychain
- common commands for search, fetch, query, create, update, and append
- a
raw command for full API coverage
Credential source
The CLI resolves credentials in this order:
NOTION_API_KEY- macOS Keychain item with service
codex-notion-api-key
Do not paste the token into working notes or output unless the user explicitly asks.
Quick start
Use the bundled script:
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py whoami
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py search --query "Knowledge Base"
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py query <database_id> --page-size 10
Common workflow
- Search for the target page or database.
- Retrieve the page or database object to inspect IDs and properties.
- Query the database to inspect current rows and schema usage.
- Create or update pages with explicit property payloads.
- Append child blocks when the page body needs structured content.
- Use
raw for any endpoint not covered by a convenience command.
Commands
Identify the integration
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py whoami
Search
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py search --query "Master Database"
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py search --query "Riley Brown" --filter-object page
Retrieve page, database, or block
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py get page <page_id>
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py get database <database_id>
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py get block <block_id>
Query a database
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py query <database_id> --page-size 25
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py query <database_id> --filter-json '{"property":"Name","title":{"contains":"Riley"}}'
Create or update a page
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py create-page \
--parent-database-id <database_id> \
--properties-json '{"Name":{"title":[{"text":{"content":"Short Form Video SOPs"}}]}}'
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py update-page <page_id> \
--properties-json '{"Status":{"select":{"name":"Draft"}}}'
Append blocks
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py append-blocks <block_id> \
--children-json '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello"}}]}}]'
Raw endpoint access
Use this when a convenience command does not exist.
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py raw POST /databases/<database_id>/query
python3 /Users/rileybrown/.codex/skills/notion-full-control/scripts/notion_api.py raw PATCH /pages/<page_id> --body-json '{"archived":false}'
Guidance
- Prefer inspecting the database schema before writing properties. Notion property payloads are exacting.
- When working in a database, retrieve the database object first and map user-facing property names to the actual property types.
- For page bodies, append blocks after page creation instead of overloading page properties.
- For unsupported operations, use
raw rather than improvising the HTTP shape.
Output discipline
- Keep IDs, URLs, and property payloads exact.
- Return concise summaries to the user, but keep raw API results available in the terminal workflow when needed.
- If a request fails, inspect the returned JSON error before retrying.
