notion

Notion Workspace Management SOP

Manage Notion content programmatically: create and update pages, query databases, write blocks, and automate workspace workflows via the Notion REST API.

When to Use

• User wants to create a new Notion page or sub-page
• User wants to add records to a Notion database
• User wants to query a database with filters or sorts
• User wants to update existing page content or properties
• User wants to read a page's blocks or a database's schema

---

Part 1 — Auth Setup

1. Create an Integration

1. Go to https://www.notion.so/profile/integrations
2. Click New integration → give it a name → select the workspace
3. Copy the Internal Integration Secret — this is your NOTION_API_KEY

2. Connect Pages to the Integration

Every page or database the integration should access must be explicitly shared:

1. Open the page/database in Notion
2. Click ... (top right) → Connections → find your integration → Confirm

3. Set the Environment Variable

export NOTION_API_KEY="secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Or store it in ~/.cowrangler/credentials.env:

NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Auth Helper (shell)

NOTION_API_KEY="${NOTION_API_KEY:-$(grep '^NOTION_API_KEY=' ~/.cowrangler/credentials.env 2>/dev/null | cut -d= -f2 | tr -d '\n\r')}"
NOTION_VERSION="2022-06-28"

notion_get() {
  curl -s -X GET "https://api.notion.com/v1/$1" \
    -H "Authorization: Bearer $NOTION_API_KEY" \
    -H "Notion-Version: $NOTION_VERSION" \
    -H "Content-Type: application/json"
}

notion_post() {
  curl -s -X POST "https://api.notion.com/v1/$1" \
    -H "Authorization: Bearer $NOTION_API_KEY" \
    -H "Notion-Version: $NOTION_VERSION" \
    -H "Content-Type: application/json" \
    -d "$2"
}

notion_patch() {
  curl -s -X PATCH "https://api.notion.com/v1/$1" \
    -H "Authorization: Bearer $NOTION_API_KEY" \
    -H "Notion-Version: $NOTION_VERSION" \
    -H "Content-Type: application/json" \
    -d "$2"
}