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

• - uxc is installed and available in PATH.
• Network access to https://api.notion.com/v1.
• Access to the curated OpenAPI schema URL:

• - A Notion integration token or OAuth credential with content read access.
• For writes, the integration also needs the corresponding Notion insert/update content capabilities.

Scope

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

• - token identity validation
• title search for pages, data sources, and databases
• page lookup
• block lookup
• recursive traversal via block-children pagination
• page property retrieval
• page creation
• page updates, including trash/restore via INLINECODE6
• block append
• block updates
• block deletion
• data source retrieval and query
• legacy database retrieval and query

This skill does not cover:

• - full Notion REST coverage
• comments, file uploads, webhooks, page move, or schema mutation
• automatic recursive traversal loops inside one single command

Endpoint And Version

• - base URL: INLINECODE7
• required version header for this skill: INLINECODE8

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:

• - INLINECODE9
• INLINECODE10

Recommended: dedicated REST credential

If you already have an internal integration token:

CODEBLOCK0

How to get the internal integration token:

1. 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:

CODEBLOCK1

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:

• - once an OAuth credential uses custom headers, include Authorization=Bearer {{secret}} explicitly
• adding Notion-Version=2026-03-11 on the shared credential means the same header will also be sent to INLINECODE19
• that extra header is expected to be harmless, but this is an interoperability assumption rather than an explicit Notion guarantee

Shared-credential setup:

CODEBLOCK2

Validate the effective mapping when auth looks wrong:

CODEBLOCK3

Core Workflow

1. 1. Use the fixed link command by default:

1. 2. Inspect operation schema first:

1. 3. Prefer read validation before broader traversal:

1. 4. Traverse recursively outside the API call boundary:

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

1. 6. Execute writes only after explicit user confirmation:

Operation Groups

Session / Discovery

• - INLINECODE41
• INLINECODE42

Page And Block Traversal

• - INLINECODE43
• INLINECODE44
• INLINECODE45
• INLINECODE46

Page And Block Writes

• - INLINECODE47
• INLINECODE48
• INLINECODE49
• INLINECODE50
• INLINECODE51

Data Source Reads

• - INLINECODE52
• INLINECODE53

Legacy Database Reads

• - INLINECODE54
• INLINECODE55

Guardrails

• - Keep automation on the JSON output envelope; do not use --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• This skill fixes Notion-Version at the credential/header layer instead of requiring it as an operation argument. Keep the credential header on 2026-03-11 unless you intentionally migrate the whole skill surface.
• This skill is read-first, but it now includes common content writes. Always confirm intent before post:/pages, patch:/pages/{page_id}, patch:/blocks/{block_id}/children, patch:/blocks/{block_id}, or delete:/blocks/{block_id}.
• On Notion API version 2026-03-11, archived has been replaced by in_trash for request and response semantics. Prefer in_trash in update payloads.
• INLINECODE73 supports up to 100 new children in one request and up to two levels of nested blocks in a single payload.
• INLINECODE74 updates block content, but it does not update child lists. Use patch:/blocks/{block_id}/children to append nested content.
• Prefer data_sources endpoints over legacy databases endpoints for new workflows. Keep legacy database reads only for compatibility with older shared links and IDs.
• INLINECODE78 returns only one nesting level at a time. Recursive traversal must be performed by repeated calls.
• Notion may return fewer results than page_size; always check has_more and next_cursor.
• INLINECODE82 is equivalent to uxc https://api.notion.com/v1 --schema-url <notion_openapi_schema> <operation> ....

References

• - Usage patterns: INLINECODE84
• Curated OpenAPI schema: INLINECODE85
• Notion API reference: https://developers.notion.com/reference
• Retrieve a database: https://developers.notion.com/reference/retrieve-a-database
• Retrieve a block: https://developers.notion.com/reference/retrieve-a-block
• Versioning: https://developers.notion.com/reference/versioning