UXC

One CLI for tools across protocols.

Notion Public API Skill

Use this skill to run Notion Public API operations through uxc + OpenAPI.

Reuse the uxc skill for shared execution, OAuth, and error-handling guidance.

Prerequisites

Scope

This skill covers a read-first Notion REST surface focused on traversal plus common content writes:

This skill does not cover:

Endpoint And Version

The schema is intentionally curated around traversal and schema discovery. It is not a full dump of the Notion API.

Authentication

Notion Public API requires:

Recommended: dedicated REST credential

If you already have an internal integration token:

uxc auth credential set notion-openapi \
  --auth-type api_key \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11" \
  --secret-env NOTION_API_TOKEN

uxc auth binding add \
  --id notion-openapi \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-openapi \
  --priority 100

How to get the internal integration token:

  1. Open the Notion integrations dashboard and create an internal integration for your workspace.
  2. In the integration configuration page, copy the API secret shown by Notion.
  3. In Notion UI, open each target page, data source, or database and add this integration via Share or Connections.
  4. Use that API secret as NOTION_API_TOKEN or pass it directly to uxc auth credential set.

Without connecting the integration to the target content, REST calls may authenticate successfully but still fail with access errors or return incomplete search results.

If you want OAuth-managed tokens for the REST host:

uxc auth oauth start notion-openapi \
  --endpoint https://api.notion.com/v1 \
  --redirect-uri http://127.0.0.1:8788/callback \
  --client-id <client_id> \
  --scope read

uxc auth oauth complete notion-openapi \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...'

uxc auth credential set notion-openapi \
  --auth-type oauth \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11"

uxc auth binding add \
  --id notion-openapi \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-openapi \
  --priority 100

Advanced: reuse the same OAuth credential as notion-mcp

This is technically possible in uxc if the existing credential already has a valid Notion OAuth access token.

Important:

Shared-credential setup:

uxc auth credential set notion-mcp \
  --auth-type oauth \
  --header "Authorization=Bearer {{secret}}" \
  --header "Notion-Version=2026-03-11"

uxc auth binding add \
  --id notion-openapi-shared \
  --host api.notion.com \
  --path-prefix /v1 \
  --scheme https \
  --credential notion-mcp \
  --priority 100

Validate the effective mapping when auth looks wrong:

uxc auth binding match https://api.notion.com/v1

Core Workflow

  1. Use the fixed link command by default:

    • command -v notion-openapi-cli
    • If missing, create it: uxc link notion-openapi-cli https://api.notion.com/v1 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/notion-openapi-skill/references/notion-public.openapi.json
    • notion-openapi-cli -h

  2. Inspect operation schema first:

    • notion-openapi-cli post:/search -h
    • notion-openapi-cli get:/blocks/{block_id}/children -h
    • notion-openapi-cli post:/pages -h
    • notion-openapi-cli patch:/blocks/{block_id}/children -h
    • notion-openapi-cli post:/data_sources/{data_source_id}/query -h

  3. Prefer read validation before broader traversal:

    • notion-openapi-cli get:/users/me
    • notion-openapi-cli post:/search '{"query":"Roadmap","filter":{"property":"object","value":"page"},"page_size":10}'
    • notion-openapi-cli get:/blocks/{block_id}/children block_id=<uuid> page_size=100

  4. Traverse recursively outside the API call boundary:

    • use get:/blocks/{block_id}/children page by page
    • for every returned child block with has_children=true, call get:/blocks/{block_id}/children again on that child ID

  5. Use data source or legacy database reads to discover schema before property-sensitive queries:

    • notion-openapi-cli get:/data_sources/{data_source_id} data_source_id=<uuid>
    • notion-openapi-cli post:/data_sources/{data_source_id}/query data_source_id=<uuid> '{"page_size":25}'
    • notion-openapi-cli get:/databases/{database_id} database_id=<uuid>

  6. Execute writes only after explicit user confirmation:

    • create page: notion-openapi-cli post:/pages '{...}'
    • append blocks: notion-openapi-cli patch:/blocks/{block_id}/children '{...}'
    • update page or block: notion-openapi-cli patch:/pages/{page_id} '{...}'
    • delete block: notion-openapi-cli delete:/blocks/{block_id} block_id=<uuid>

Operation Groups

Session / Discovery

Page And Block Traversal

Page And Block Writes

Data Source Reads

Legacy Database Reads

Guardrails

References