# Notion

Read and update Notion pages and databases.

URL: https://docs.qaldy.com/connectors/notion/

- **Status:** [[Available]]
- **Shelf:** Data and docs
- **How you connect:** API key
- **Regions:** global (not available to Kazakhstan-only workspaces)
- **The service’s own API reference:** https://developers.notion.com/reference/intro

Apps read and update Notion pages and databases through an **internal integration**. Notion is
reached through the HTTP API connector with a preset: the gate calls only `api.notion.com/v1`, with
`GET`, `POST` and `PATCH`, and always sends `Notion-Version: 2022-06-28`. The integration secret is
sealed to the gate and apps never see it.

> **Status: Available through the HTTP API preset.** The preset follows Notion's API reference
> (checked 2026-10-16). It has not been run against a live workspace.

## Connect it

1. In Notion, open **Settings → Connections → Develop or manage integrations**
   ([notion.so/profile/integrations](https://www.notion.so/profile/integrations)) and create an
   **internal** integration. Give it only the capabilities the apps need (read, update, insert).
2. Copy the **Internal Integration Secret**.
3. On every page or database the apps need, open the **three-dot menu → Connections** and add the
   integration. Notion shows an integration only what is shared with it, so this is also the
   fence on what it can see.
4. Qaldy → **Connectors** → Notion → **Connect Notion** → paste the secret → **Seal and connect**.

**Test connection** calls `GET /v1/users/me`, which answers for any valid integration.

## What the gate allows

| | |
|---|---|
| Host | `api.notion.com`, base path `/v1` (pinned, every resolved address public) |
| Methods | `GET`, `POST`, `PATCH` (no `DELETE`: Notion archives pages with `PATCH`) |
| Paths | everything under `/v1` (`/pages`, `/databases`, `/blocks`, `/search`, `/users`) |
| Key | `Authorization: Bearer <secret>`, added by the gate |
| Fixed header | `Notion-Version: 2022-06-28`; an app can't override it |

## Use it from an app

```json
{ "id": "http", "actions": ["request"], "scope": "conn_k3v9…" }
```

```ts
const api = ctx.connectors.http('conn_k3v9…')
const rows = await api.post('/databases/<database id>/query', { json: { page_size: 20 } })
await api.post('/pages', { json: { parent: { database_id: '<database id>' }, properties: {} } })
```

## When it breaks

| You see | Why | Do |
|---|---|---|
| `401` | The secret was revoked or mistyped | Replace the secret |
| `404 object_not_found` | The page or database isn't shared with the integration | Add the connection on that page |
| `403 restricted_resource` | The integration lacks the capability | Edit its capabilities in Notion |