# Connect Notion

> Know when a Notion row lands on you, a page you care about changes, or someone comments. Read with your own personal access token, straight from your Mac.

Source: https://coisland.app/docs/connect-notion/

## What you need

- **You need:** Personal access token, from Developer portal › Personal access tokens
- **The form asks:** Connector name, Token
- **You can watch:** Database rows, Edited pages, Comments
- **Access:** Reads and searches only; it never edits a page

To connect Notion to CoIsland you need one token you create yourself: a **personal access token**, which reads what you can, or, if your workspace does not let you make one, an **internal integration's secret**, which reads only the pages shared with it. No OAuth app, nothing to register. CoIsland calls Notion's API straight from your Mac, keeps the token in your login Keychain, and only ever reads.

## Create a Notion personal access token

1. Open Notion's **Developer portal**, then **Personal access tokens**.
2. Select **New token**. Name it, such as `CoIsland`, tick the **Notion API** capability, and pick an expiration (7, 30, 90 or 180 days, or 1 year).
3. Select **Create token** and copy it now: Notion shows it only once.

The token acts as you: CoIsland sees the pages and databases you can see, with no page to share. Who may create one depends on the plan: every full member on Plus; only workspace owners on Free and on Business, unless a Business admin allows all members; owners and the groups an admin picks on Enterprise. Guests and restricted members cannot.

### No personal access token? Use an internal integration

1. In the Developer portal, open **Internal connections** and create one for your workspace; copy its secret.
2. In Notion, open each database to watch, then **•••** › **Connections**, and add the integration.

An integration is a bot: it sees only what is shared with it, and "assigned to me" means the bot, so the **Assigned to me in** field matches nothing with it.

## Connect Notion in CoIsland

Open **Settings › Connectors**, click **+**, and choose **Notion**.

| Field | What to enter |
|---|---|
| Connector name | What monitors call it: `notion`. Letters, digits, `_` and `-`. |
| Token | The personal access token, or the integration's secret. |

**Test connector** calls `GET /v1/users/me` and searches for databases: a personal token reads your name and email, an integration reads **Internal integration** and its workspace, then how many databases the token sees. It saves nothing. **Add Connector** keeps the name in `~/Library/Application Support/CoIsland/connectors.json` and the token in your login Keychain; the token is only ever sent to `https://api.notion.com`, in the `Authorization` header.

## Choose what to watch: the three Notion monitor kinds

The first line of a Notion query is a few `key:value` words the editor's fields write for you: the database (`source:`, picked by name), a people property that must hold you (`person:`), and for edits a window and `by:others`. The lines after are an optional filter in Notion's own JSON, as its API takes it. A new-items monitor's first check records what is there and raises nothing.

### Database rows

A row alerts when it starts matching: here, rows whose Assignee is you and whose status is not Done.

```text
source:1f2e3d4c-5b6a-4798-8796-a5b4c3d2e1f0 person:a%5Bq
{"property":"Status","status":{"does_not_equal":"Done"}}
```

### Edited pages

Pages of the database edited within `within:` (`1h`, `6h`, `24h` or `7d`; `24h` unless given). Each edit alerts once; `by:others` leaves out the pages you edited last.

```text
source:1f2e3d4c-5b6a-4798-8796-a5b4c3d2e1f0 within:24h by:others
```

### Comments

New open comments on one to ten pages, picked by title; `by:others` leaves out yours. Notion's API lists open comments only.

```text
page:11111111222243338444555555555555 by:others
```

## What a Notion alert shows

The notch lists a row as `TASK-12 · In progress · Due: 2026-09-25`, and a comment as `Launch plan · Comment · Ben Okafor`. Clicking opens the alert in CoIsland, where the page fills in live: every property, its text (headings, paragraphs, lists, to-dos, quotes and code), its open comments with the one the alert is about highlighted, and **Open in Notion**.

## What a Notion monitor's watch file looks like

```sql
-- name: My open tasks
-- kind: notion.rows
-- connector: notion
-- alert: new-rows

source:1f2e3d4c-5b6a-4798-8796-a5b4c3d2e1f0 person:a%5Bq
{"property":"Status","status":{"does_not_equal":"Done"}}
```

The kinds are `notion.rows`, `notion.edited` and `notion.comments`. [Watch files](https://coisland.app/docs/watch-files/) lists every header key.

## Rate limits

Notion allows each connection an average of 3 requests a second (10 on Business and Enterprise), and limits a workspace as a whole too. A database check costs two requests for 100 rows, a comments check two per page. When Notion asks CoIsland to slow down, checks back off on their own.

## Troubleshooting Notion connector errors

- **The token was refused.** Notion answered 401: the token expired, was revoked, or your workspace's admins no longer allow personal access tokens for you. Create a new one.
- **… was not found. It was deleted, or it is not shared with this token.** Notion answered 404. With an integration, add it to the database under **•••** › **Connections**.
- **… not allowed.** Notion answered 403: the token lacks a capability, such as reading comments.
- **Notion refused the request:** then Notion's words, such as a filter naming a property the database does not have.
- **The filter is not a JSON object like …** The lines after the first must be one JSON object, Notion's filter.