Overview

Pyckle integrates with Notion through OAuth 2.0. You create a Notion integration once, authorize it from your browser, and receive an access token. The token is per-user and scoped to the specific databases you share with the integration. Once connected, your Notion content becomes searchable alongside your codebase through the same search_code() interface.

Step 1 — Create a Notion Integration

Go to notion.so/my-integrations and click New integration.

Name: "Pyckle" (or any name you prefer)
Type: Public integration (required for OAuth — Internal won't work)
Redirect URIs: https://pyckle.co/auth/notion/callback (exact match, no trailing slash)
Capabilities: Read content, Read user information

Save the Client ID and Client Secret — you'll need both in the next step.

Important You must choose "Public integration". Internal integrations don't support OAuth redirects.

Step 2 — Set Credentials on Fly

Store your Notion credentials as secrets in your Fly.io deployment:

fly secrets set -a pyckle \
  NOTION_CLIENT_ID= \
  NOTION_CLIENT_SECRET= \
  NOTION_REDIRECT_URI="https://pyckle.co/auth/notion/callback"

Step 3 — Authorize the Integration

Open this URL in your browser (replace my_workspace with any string you want to use as a state identifier):

https://pyckle.co/auth/notion?state=my_workspace

You'll be redirected to Notion's authorization page. Click Allow. On success, the response JSON includes your access_token and workspace name.

Tip Copy and save the access_token — Pyckle doesn't store it server-side. You'll need it for index_notion().

Step 4 — Index Your Workspace

Use the index_notion() function to index your Notion content:

index_notion(
  token="ntn_xxxxx",
  database_id="your_database_id"  # optional: omit to index all shared databases
)

Step 5 — Share Databases with the Integration

In Notion: open each database you want indexed, click the ... menu, select Add connections, and choose your integration.

How Notion Permissions Work Notion only lets the integration access databases you explicitly share with it. Pages inside shared databases are automatically included.

Step 6 — Search Your Notion Content

Search your indexed Notion content alongside your code:

search_code("authentication architecture decision")

Notion results appear alongside code results, tagged with source: "notion" in the result metadata.

Troubleshooting

redirect_uri_mismatch: The redirect URI in your Notion integration must exactly match https://pyckle.co/auth/notion/callback — no trailing slash, no http://.
index_notion returns empty results: Share the target database with your integration (Step 5 above).
401 on auth endpoint: Your NOTION_CLIENT_ID or NOTION_CLIENT_SECRET is wrong. Re-run fly secrets set.