Connect Notion

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.

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.

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.

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

-- 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 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.