Notion

You have access to the Notion API via the managed OAuth connection or an internal integration secret stored in the credential vault. Both paths inject the Authorization header automatically. Never reveal credential values or echo token values into the shell.

Authentication

Step 1 - Determine connection type:

assistant credentials list

Look at the results to decide which path to use:

• Managed OAuth (preferred): No service: "notion" entry is needed in the vault. The OAuth connection is managed by the platform. Use Path A below.
• Internal integration secret: An entry with service: "notion" and field: "internal_secret" is present. Use Path A below (recommended) or Path B if the credential has the required metadata (see Path B for details).
• Neither configured: Tell the user: "Notion is not connected yet. Load the vellum-oauth-integrations skill to set it up first."

Step 2 - Make authenticated API calls:

Choose the path that matches what you found in Step 1.

Path A. Managed OAuth (preferred)

Use assistant oauth request --provider notion. The Authorization header is injected automatically; do not supply it manually.

assistant oauth request --provider notion \
  -X POST \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://api.notion.com/v1/search

General shape: assistant oauth request --provider notion -X <METHOD> -H "Notion-Version: 2022-06-28" [-H "Content-Type: application/json"] [-d '<json-body>'] <url>

• URL can be absolute (https://api.notion.com/v1/pages/...) or relative (/v1/pages/...).
• -d accepts inline JSON, @filename, or @- for stdin.
• Token refresh is handled automatically.

Path B. Proxied bash with credential auto-injection

Note: The standard Notion setup flow (vellum-oauth-integrations) does not currently produce credentials with the metadata required by this path. Most users should use Path A instead. Path B is documented for credentials that have been manually configured with the required metadata.

For internal integration secrets registered with allowedTools: ["bash"] and an injection_templates entry for api.notion.com. The proxy adds Authorization: Bearer <token> automatically. Do not include an Authorization header in the curl command.

bash:
  network_mode: proxied
  credential_ids: ["<credential_id_from_step_1>"]
  command: |
    curl -s -X POST https://api.notion.com/v1/search \
      -H "Notion-Version: 2022-06-28" \
      -H "Content-Type: application/json" \
      -d '{}'

Where <credential_id_from_step_1> is the id field from the matching entry in assistant credentials list output.

The credential MUST have:

• allowedTools including "bash" (otherwise the proxy blocks the call).
• injection_templates with host pattern api.notion.com and header injection type for Authorization.

If these are missing, you will get a credential tool policy denied error. Switch to Path A instead.

All Notion API calls go to https://api.notion.com/v1/. Always include the Notion-Version: 2022-06-28 header.

Reading Pages

Get a page by ID

GET https://api.notion.com/v1/pages/{page_id}

Returns page properties. Use the page ID from a Notion URL - the last segment of the URL, e.g. for https://notion.so/My-Page-abc123def456 the ID is abc123def456 (formatted as UUID: abc123de-f456-...).

Get page content (blocks)

GET https://api.notion.com/v1/blocks/{block_id}/children?page_size=100

Pages are blocks too - use the page ID as the block_id. Iterates through the page's child blocks. Use start_cursor for pagination when has_more is true.

Block types and how to render them:

• paragraph: Read paragraph.rich_text[].plain_text
• heading_1, heading_2, heading_3: Read heading_N.rich_text[].plain_text
• bulleted_list_item, numbered_list_item: Read *.rich_text[].plain_text
• to_do: Read to_do.rich_text[].plain_text and to_do.checked
• toggle: Read toggle.rich_text[].plain_text; children are nested blocks
• code: Read code.rich_text[].plain_text and code.language
• quote: Read quote.rich_text[].plain_text
• callout: Read callout.rich_text[].plain_text
• divider: Render as ---
• image: Read image.external.url or image.file.url
• child_page: Read child_page.title; use its id to recursively fetch if needed

Searching

Search pages and databases

POST https://api.notion.com/v1/search
{
  "query": "your search term",
  "filter": { "value": "page", "property": "object" },
  "sort": { "direction": "descending", "timestamp": "last_edited_time" },
  "page_size": 10
}

Omit filter to search both pages and databases. Use filter.value: "database" to search only databases.

Returns results[] with id, url, properties.title (for pages), and title[] (for databases).

Reading Databases

Get database metadata

GET https://api.notion.com/v1/databases/{database_id}

Returns the database schema (all property definitions).