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

```
credential_store action=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 `credential_store action=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.Own