---
id: vellum-ai/vellum-assistant/notion
version: "88f8b4e8"
license: MIT
install: manual
updated: 2026-07-28
---

# notion — Access your Notion workspace to retrieve page content, search across pages and databases, query database rows, and create or update pages programmatically. The skill handles authentication automatically through managed OAuth or internal integration credentials.

Publisher: vellum-ai · Stars: 951 · Updated: 2026-07-28

Install (manual): `git clone https://github.com/vellum-ai/vellum-assistant`

## SKILL.md

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/databases/{database_id}
```

Returns the database schema (all property definitions).

### Query a database

```
POST https://api.notion.com/v1/databases/{database_id}/query
{
  "filter": {
    "property": "Status",
    "select": { "equals": "In Progress" }
  },
  "sorts": [
    { "property": "Created", "direction": "descending" }
  ],
  "page_size": 20
}
```

Omit `filter` to retrieve all rows. Returns `results[]` where each item is a page (database row).

**Extracting property values from database rows:**

- `title`: `properties.Name.title[].plain_text`
- `rich_text`: `properties.Notes.rich_text[].plain_text`
- `number`: `properties.Price.number`
- `select`: `properties.Status.select.name`
- `multi_select`: `properties.Tags.multi_select[].name`
- `date`: `properties.Due.date.start` (ISO 8601)
- `checkbox`: `properties.Done.checkbox`
- `url`: `properties.Link.url`
- `email`: `properties.Email.email`
- `people`: `properties.Owner.people[].name`
- `relation`: `properties.Projects.relation[].id` (array of page IDs)

## Creating Pages

### Create a new page

```
POST https://api.notion.com/v1/pages
{
  "parent": { "page_id": "<parent_page_id>" },
  "properties": {
    "title": {
      "title": [{ "text": { "content": "My New Page" } }]
    }
  },
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{ "text": { "content": "Page content here." } }]
      }
    }
  ]
}
```

For database rows, use `"parent": { "database_id": "<database_id>" }` and include the database's required properties.

## Updating Pages

### Update page properties

```
PATCH https://api.notion.com/v1/pages/{page_id}
{
  "properties": {
    "Status": { "select": { "name": "Done" } },
    "Due": { "date": { "start": "2024-12-31" } }
  }
}
```

### Append blocks to a page

```
PATCH https://api.notion.com/v1/blocks/{block_id}/children
{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{ "text": { "content": "Appended content." } }]
      }
    },
    {
      "object": "block",
      "type": "heading_2",
      "heading_2": {
        "rich_text": [{ "text": { "content": "A heading" } }]
      }
    },
    {
      "object": "block",
      "type": "bulleted_list_item",
      "bulleted_list_item": {
        "rich_text": [{ "text": { "content": "A bullet point" } }]
      }
    },
    {
      "object": "block",
      "type": "to_do",
      "to_do": {
        "rich_text": [{ "text": { "content": "A task" } }],
        "checked": false
      }
    }
  ]
}
```

### Update a block's content

```
PATCH https://api.notion.com/v1/blocks/{block_id}
{
  "paragraph": {
    "rich_text": [{ "text": { "content": "Updated text." } }]
  }
}
```

### Delete (archive) a block

```
DELETE https://api.notion.com/v1/blocks/{block_id}
```

## Archive / Delete Pages

Notion does not permanently delete pages via the API - it archives them:

```
PATCH https://api.notion.com/v1/pages/{page_id}
{
  "archived": true
}
```

## Pagination

When a response includes `"has_more": true`, pass `"start_cursor": response.next_cursor` in the next request to get the next page of results.

## Error Handling

- **401 Unauthorized**: The token is missing, invalid, or expired. For Internal integrations, ask the user to re-run the **vellum-oauth-integrations** skill. For OAuth connections, the access token may need to be refreshed or re-authorized.
- **403 Forbidden**: The integration doesn't have access to the requested page or database. Remind the user that they need to share the page/database with the "Vellum Assistant" integration in Notion (via the Share menu → "Add connections").
- **404 Not Found**: The page or database ID doesn't exist or the integration can't see it. Verify the ID and check sharing settings.
- **400 Bad Request**: Check the request body structure. The Notion API error response includes a `message` field with details.
- **429 Too Many Requests**: Wait a few seconds and retry.
- **`credential tool policy denied`**: The credential is missing `bash` in `allowedTools` or an `injection_templates` entry for `api.notion.com`, so the proxy cannot inject the Authorization header. Switch to **Path A** (managed OAuth), which bypasses credential metadata requirements entirely.

## Tips

- Notion page IDs in URLs are formatted without hyphens. The API accepts both forms: `abc123def456...` or `abc123de-f456-...`.
- When extracting IDs from Notion URLs, strip any query parameters and trailing path components after the 32-character ID segment.
- Always include `Notion-Version: 2022-06-28` header to get stable API behavior.
- For rich text, concatenate all `plain_text` values in the array to get the full text content.
- When creating content with rich text formatting (bold, italic, links), use the `annotations` and `href` fields in rich_text objects.


[View on SkillFed](https://skillfed.io/vellum-ai/vellum-assistant/notion) · [View on GitHub](https://github.com/vellum-ai/vellum-assistant)