Notion

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/skills/notionThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Read and write Notion pages and databases using the Notion API

---
name: notion
description: Read and write Notion pages and databases using the Notion API
compatibility: "Designed for Vellum personal assistants"
metadata:
  icon: assets/icon.svg
  emoji: "📝"
  vellum:
    category: "productivity"
    display-name: "Notion"
    activation-hints:
      - "User asks to read, find, search, or open a page, doc, database, or directory in their Notion (e.g. 'find it in notion', 'look in my Notion', 'this is a notion directory')"
      - "User references Notion content by name or path and wants its contents pulled"
      - "User wants to create, update, append to, or query Notion pages or databases"
      - "User asks anything that requires reading or writing Notion data, including checking a task list or workspace held in Notion"
    avoid-when:
      - "User wants to set up, connect, or reconnect the Notion OAuth integration for the first time; load vellum-oauth-integrations instead"
---

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:**

```bash
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/datab

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vellum-ai/vellum-assistant
git -C vellum-assistant checkout 19bc86343b63

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 19bc86343b63

Questions about Notion

• github.com/vellum-ai/vellum-assistant/tree/main/skills/notion — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology