How to Integrate Replit with Notion

Go to notion.so/my-integrations (or navigate to Settings > Integrations in Notion, then click 'Develop your own integrations'). Click 'New integration'. Give it a name like 'Replit App' and select the Workspace it should belong to. Set the integration type to 'Internal' — this is correct for server-side Replit apps that access your own Notion workspace. Under Capabilities, choose what the integration can do: Read content (to query databases and read pages), Update content (to modify existing pages), Insert content (to create new pages). Only enable the capabilities your app actually needs. Click 'Submit'. Notion will display your Internal Integration Secret — a token starting with 'secret_'. Copy this token immediately. Notion integration tokens don't expire, but they should be treated as sensitive credentials — anyone with this token has the access level you configured. If the token is ever compromised, you can generate a new one from the same integration settings page and update your Replit Secret.

This is the most commonly missed step when setting up a Notion integration. By default, your integration has no access to any pages or databases — you must explicitly grant access. Open the Notion database or page you want your Replit app to access. Click the three-dot menu (...) in the top right corner, or click 'Share' if visible. In the share dialog, look for 'Connections' (in newer Notion UI) or 'Invite' (in older UI). Search for your integration name and click it to grant access. The integration now has access to this database and all pages within it. You also need the database ID, which you can find in the database's URL when you open it in a browser: it's the 32-character string in the URL path after the workspace name and before any query parameters. For example, in https://notion.so/myworkspace/abc123def456...?v=..., the database ID is abc123def456... — format it with hyphens as a UUID: abc123de-f456-...-... for the API calls (the SDK handles this automatically if you pass the raw ID).

1# Python — extract Notion database ID from URL
2notion_url = "https://www.notion.so/myworkspace/abc123def4561234abcd1234567890ab?v=..."
3# The database ID is the 32-char hex string before '?'
4path = notion_url.split('?')[0].split('/')[-1]
5# Remove hyphens if present, then reformat
6raw_id = path.replace('-', '')
7if len(raw_id) == 32:
8    formatted_id = f"{raw_id[:8]}-{raw_id[8:12]}-{raw_id[12:16]}-{raw_id[16:20]}-{raw_id[20:]}"
9    print(f"Database ID: {formatted_id}")
10else:
11    print(f"URL format unexpected, raw path: {path}")

Open your Repl and click the lock icon (🔒) in the left sidebar to open the Secrets pane. Add NOTION_TOKEN with your integration secret (starting with 'secret_') as the value. Also add NOTION_DATABASE_ID with your database's UUID-formatted ID. Having the database ID as a secret makes it easy to switch between different Notion databases for staging and production without code changes. Replit Secrets are AES-256 encrypted and injected as environment variables — they are never stored in code or visible in Git history. After adding the secrets, verify they are accessible in your Repl by running a quick check script. Install the Notion SDK — in Node.js run npm install @notionhq/client, in Python add notion-client to requirements.txt or install via the Packages pane.

1// Node.js — verify Notion secrets (check.js)
2const requiredSecrets = ['NOTION_TOKEN', 'NOTION_DATABASE_ID'];
3for (const key of requiredSecrets) {
4  const val = process.env[key];
5  if (!val) {
6    throw new Error(`${key} not found. Add it in Replit Secrets (lock icon 🔒).`);
7  }
8  console.log(`${key}: loaded (${val.length} chars)`);
9}
10console.log('All Notion secrets verified.');

The Notion API's database query endpoint lets you retrieve pages from a database with optional filters and sorting. Using the official @notionhq/client SDK, call client.databases.query() with your database ID and optional filter and sorts parameters. Filters follow a structured format: each filter specifies a property name, the property type (rich_text, number, date, select, etc.), and the filter condition (equals, contains, after, etc.). Multiple filters can be combined with and/or logic. The query returns a results array of Notion page objects. Each page contains an id, a properties object with typed property values, and a url. Property values are deeply nested — a text property value is at properties.Name.title[0].plain_text, while a select value is at properties.Status.select.name. The SDK includes TypeScript types if you're using TypeScript, making it easier to navigate these nested structures. For plain Node.js, log the full response of a few pages to understand your specific database's property structure before building display logic.

1// Node.js — Query Notion database (notion.js)
2const { Client } = require('@notionhq/client');
3
4const notion = new Client({ auth: process.env.NOTION_TOKEN });
5const DATABASE_ID = process.env.NOTION_DATABASE_ID;
6
7async function queryDatabase({ filter = null, sorts = null, pageSize = 100 } = {}) {
8  const params = { database_id: DATABASE_ID, page_size: pageSize };
9  if (filter) params.filter = filter;
10  if (sorts) params.sorts = sorts;
11
12  const response = await notion.databases.query(params);
13  return response.results;
14}
15
16// Helper to extract plain text from Notion title property
17function getTitle(page) {
18  const titleProp = Object.values(page.properties)
19    .find(p => p.type === 'title');
20  return titleProp?.title[0]?.plain_text || 'Untitled';
21}
22
23// Example: get all pages with Status = 'Published'
24async function getPublishedPages() {
25  return queryDatabase({
26    filter: {
27      property: 'Status',
28      select: { equals: 'Published' }
29    },
30    sorts: [{ property: 'Published Date', direction: 'descending' }]
31  });
32}
33
34module.exports = { notion, queryDatabase, getTitle, DATABASE_ID };

Creating a new database entry uses client.pages.create() with the database as the parent and a properties object that matches your database schema. Each property value must be formatted according to its Notion property type — text values use the rich_text type with an array of text objects, selects use the select type with a name string, dates use the date type with a start string in ISO 8601 format, numbers use the number type directly. Getting this structure right is the trickiest part of the Notion API. The best approach is to first query an existing page in your database and log its properties — the structure of existing values shows you exactly how to format new values. For updating existing pages, use client.pages.update() with the page ID and only the properties you want to change. You can also add block content to a page using client.blocks.children.append() to add paragraphs, headings, lists, code blocks, and more.

1// Node.js — Create and update Notion pages (crud.js)
2const { notion, DATABASE_ID } = require('./notion');
3
4async function createPage({ title, status, publishDate, tags = [] }) {
5  const page = await notion.pages.create({
6    parent: { database_id: DATABASE_ID },
7    properties: {
8      // Title property (adjust 'Name' to match your database's title column)
9      Name: {
10        title: [{ text: { content: title } }]
11      },
12      // Select property
13      Status: {
14        select: { name: status }
15      },
16      // Date property
17      'Publish Date': {
18        date: publishDate ? { start: publishDate } : null
19      },
20      // Multi-select property
21      Tags: {
22        multi_select: tags.map(tag => ({ name: tag }))
23      }
24    }
25  });
26  return page;
27}
28
29async function updatePage(pageId, updates) {
30  return notion.pages.update({
31    page_id: pageId,
32    properties: updates
33  });
34}
35
36async function addContentBlock(pageId, text) {
37  return notion.blocks.children.append({
38    block_id: pageId,
39    children: [{
40      object: 'block',
41      type: 'paragraph',
42      paragraph: {
43        rich_text: [{ type: 'text', text: { content: text } }]
44      }
45    }]
46  });
47}
48
49module.exports = { createPage, updatePage, addContentBlock };

The Python notion-client package (pip install notion-client) provides the same interface as the Node.js SDK. Install it via the Packages pane or add to requirements.txt. The Python client uses snake_case method names: client.databases.query(), client.pages.create(), client.blocks.children.append(). Property value structures are identical to Node.js — the same nested dictionaries apply. For querying, pass filter and sorts as Python dictionaries. The pagination cursor works the same way: check has_more and pass start_cursor to the next query call to retrieve subsequent pages. If you prefer to call the Notion API without the SDK, use the requests library with Authorization: Bearer {NOTION_TOKEN} and a Notion-Version: 2022-06-28 header on all requests — the version header is required by the API.

1# Python — Flask Notion integration (app.py)
2import os
3from flask import Flask, request, jsonify
4from notion_client import Client
5
6app = Flask(__name__)
7
8notion = Client(auth=os.environ["NOTION_TOKEN"])
9DATABASE_ID = os.environ["NOTION_DATABASE_ID"]
10
11@app.route("/database", methods=["GET"])
12def list_entries():
13    filter_status = request.args.get("status")
14    params = {"database_id": DATABASE_ID, "page_size": 50}
15    if filter_status:
16        params["filter"] = {
17            "property": "Status",
18            "select": {"equals": filter_status}
19        }
20    response = notion.databases.query(**params)
21    results = []
22    for page in response["results"]:
23        title_prop = next(
24            (p for p in page["properties"].values() if p["type"] == "title"), None
25        )
26        title = title_prop["title"][0]["plain_text"] if title_prop and title_prop["title"] else "Untitled"
27        results.append({"id": page["id"], "title": title, "url": page["url"]})
28    return jsonify(results)
29
30@app.route("/pages", methods=["POST"])
31def create_page():
32    data = request.get_json()
33    page = notion.pages.create(
34        parent={"database_id": DATABASE_ID},
35        properties={
36            "Name": {"title": [{"text": {"content": data["title"]}}]},
37            "Status": {"select": {"name": data.get("status", "Draft")}}
38        }
39    )
40    return jsonify({"id": page["id"], "url": page["url"]})
41
42if __name__ == "__main__":
43    app.run(host="0.0.0.0", port=3000)