Notion Setup Guide

Status: Step-by-Step Guide | Last Updated: 2026-02-20

---

Prerequisites

• Notion account (free or paid)
• Admin access to Notion workspace
• Access to backend server for configuration

---

Step 1: Create Notion Integration

1.1 Navigate to Integrations Page

1. Go to https://www.notion.so/my-integrations
2. Click "+ New integration"

1.2 Configure Integration

Basic Information:

• Name: Yappa Knowledge Hub (or your preferred name)
• Logo: Upload your app logo (optional)
• Associated workspace: Select your workspace

Capabilities (Required):

• Read content - For querying databases and pages
• Update content - For updating existing pages
• Insert content - For creating new pages

Content Capabilities:

• Read user information including email addresses (optional)
• No user information (if you don't need user data)

Integration Type:

• Select Internal integration (recommended for private use)
• Or Public integration (if building for distribution)

1.3 Save and Copy Token

1. Click "Submit" to create the integration
2. Copy the Internal Integration Token (starts with ntn_)
3. Save this token securely - you'll need it for configuration

Example Token Format:

ntn_60820166101ufBfMmW2y3WNUjtyN5de47PlkaEGAmK3nH

---

Step 2: Create Notion Databases

2.1 Create Knowledge Items Database

1. Create a new page in your Notion workspace
2. Add a database (Table view recommended)
3. Name it: Knowledge Items

Add Properties:

Property Name	Type	Configuration
Title	Title	(Default, already exists)
Content	Text	Rich text enabled
Tags	Multi-select	Add common tags: documentation, tutorial, reference, best-practice, etc.
Status	Status	Options: Not started, In progress, Done
Categories	Relation	(Will configure after creating Categories DB)
Source URL	URL	-
Author	Person	-
Attachments	Files & media	-
Slack ID	Text	-
Channel	Text	-
TS	Text	-
AI Summary	Text	Rich text enabled

Steps to Add Property:

1. Click "+" in the property header row
2. Select property type
3. Name the property (exact name matters!)
4. Configure options (for select/multi-select)

2.2 Create Categories Database

1. Create another new page in your workspace
2. Add a database (Table or Gallery view)
3. Name it: Categories

Add Properties:

Property Name	Type	Configuration
Title	Title	(Default, already exists)
Description	Text	Rich text enabled
Default Target Groups	Multi-select	Options: Developers, DevOps, Product Managers, Designers, QA, All
Knowledge Items	Relation	Link to Knowledge Items database
Digest Reports	Relation	(Will configure after creating Digests DB)
Subscribers	Person	Multiple people allowed
Rollup	Rollup	Relation: Knowledge Items, Property: Title, Calculate: Count all
Created	Created time	Auto-populated

Configure Knowledge Items Relation:

1. Click "+" to add property
2. Select "Relation"
3. Name it: Knowledge Items
4. Select the Knowledge Items database you created
5. Enable "Show on Knowledge Items" (creates bidirectional relation)
6. Name the reverse relation: Categories

2.3 Create Digest Reports Database

1. Create another new page in your workspace
2. Add a database (Table view)
3. Name it: Digest Reports

Add Properties:

Property Name	Type	Configuration
Title	Title	(Default, already exists)
Period Start	Date	-
Period End	Date	-
Status	Status	Options: Not started, In progress, Done
Items Count	Number	Format: Number
Categories	Relation	Link to Categories database
Generated By	Person	-
Generated At	Created time	Auto-populated
Recipients	Text	-
Slack Sent	Checkbox	-
Target Groups	Multi-select	Same options as Categories: Developers, DevOps, etc.

Configure Categories Relation:

1. Add "Relation" property named Categories
2. Link to Categories database
3. Enable "Show on Categories"
4. Name reverse relation: Digest Reports

2.4 Complete Relation Setup

Now go back to Knowledge Items database:

1. Find the Categories property (should already exist from step 2.2)
2. Verify it links to Categories database
3. Test by adding a category to a knowledge item

---

Step 3: Share Databases with Integration

CRITICAL: Your integration needs explicit access to each database.

3.1 Share Knowledge Items Database

1. Open the Knowledge Items database page
2. Click the "..." menu (top right corner)
3. Scroll down and click "Add connections"
4. Find and select "Yappa Knowledge Hub" (your integration name)
5. Click "Confirm"

You should see your integration listed under "Connections".

3.2 Share Categories Database

Repeat the same process:

1. Open Categories database
2. Click "..." "Add connections"
3. Select your integration
4. Click "Confirm"

3.3 Share Digest Reports Database

Repeat for the third database:

1. Open Digest Reports database
2. Click "..." "Add connections"
3. Select your integration
4. Click "Confirm"

Verification: All three databases should now show your integration under "Connections".

---

Step 4: Get Database IDs

4.1 Method 1: From Database URL

1. Open each database in Notion
2. Copy the URL from your browser
3. Extract the database ID from the URL

URL Format:

https://www.notion.so/workspace-name/DATABASE_ID?v=VIEW_ID

Example:

https://www.notion.so/306e292a15d58004a8cbc222dcd48bb2?v=...
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                      This is your database ID

Database ID Format:

• 32 characters (hexadecimal)
• Can be with or without hyphens
• Example: 306e292a15d58004a8cbc222dcd48bb2
• Or: 306e292a-15d5-8004-a8cb-c222dcd48bb2

4.2 Method 2: Using Notion API

# List all databases accessible to your integration
curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "object",
      "value": "database"
    }
  }'

4.3 Record Your Database IDs

Create a note with your database IDs:

Knowledge Items: 306e292a-15d5-8004-a8cb-c222dcd48bb2
Categories:      306e292a-15d5-805d-ae13-e64bed8519c5
Digest Reports:  306e292a-15d5-80d7-a0f6-fe8421baff10

Note: You can use IDs with or without hyphens. The API accepts both formats.

---

Step 5: Configure Backend Environment

5.1 Update .env File

Edit backend/.env:

# Notion API Configuration
NOTION_API_KEY=ntn_YOUR_INTEGRATION_TOKEN_HERE
NOTION_VERSION=2022-06-28

# Database IDs (with or without hyphens)
NOTION_DATABASE_KNOWLEDGE=306e292a-15d5-8004-a8cb-c222dcd48bb2
NOTION_DATABASE_CATEGORIES=306e292a-15d5-805d-ae13-e64bed8519c5
NOTION_DATABASE_DIGESTS=306e292a-15d5-80d7-a0f6-fe8421baff10

Important:

• Replace ntn_YOUR_INTEGRATION_TOKEN_HERE with your actual token
• Replace database IDs with your actual IDs
• Keep NOTION_VERSION=2022-06-28 (current stable version)

5.2 Verify Configuration

cd backend

# Check environment variables are loaded
php -r "
echo 'API Key: ' . (getenv('NOTION_API_KEY') ? 'Set ' : 'Missing ') . PHP_EOL;
echo 'Version: ' . getenv('NOTION_VERSION') . PHP_EOL;
echo 'Knowledge DB: ' . getenv('NOTION_DATABASE_KNOWLEDGE') . PHP_EOL;
echo 'Categories DB: ' . getenv('NOTION_DATABASE_CATEGORIES') . PHP_EOL;
echo 'Digests DB: ' . getenv('NOTION_DATABASE_DIGESTS') . PHP_EOL;
"

Expected output:

API Key: Set
Version: 2022-06-28
Knowledge DB: 306e292a-15d5-8004-a8cb-c222dcd48bb2
Categories DB: 306e292a-15d5-805d-ae13-e64bed8519c5
Digests DB: 306e292a-15d5-80d7-a0f6-fe8421baff10

---

Step 6: Test the Integration

6.1 Test API Connectivity

# Test Knowledge Database access
curl -X POST "https://api.notion.com/v1/databases/YOUR_KNOWLEDGE_DB_ID/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 1}'

Expected Response:

{
  "object": "list",
  "results": [...],
  "has_more": false,
  "next_cursor": null
}

Common Errors:

• 401 unauthorized - Check API key
• 404 object_not_found - Database not shared with integration
• 400 validation_error - Check database ID format

6.2 Test Backend API

Start the backend server:

cd backend
php -S localhost:8000 -t public

Test endpoints:

# Get all categories
curl http://localhost:8000/api/categories

# Get all knowledge items
curl http://localhost:8000/api/knowledge

# Create a test knowledge item
curl -X POST http://localhost:8000/api/knowledge \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Knowledge Item",
    "content": "This is a test",
    "tags": ["test"]
  }'

6.3 Verify in Notion

1. Open your Knowledge Items database in Notion
2. You should see the test item created
3. Check that all properties are populated correctly

---

Step 7: Add Sample Data (Optional)

7.1 Create Sample Categories

Add these categories to your Categories database:

Title	Description	Icon	Default Target Groups
Engineering	Technical documentation and guides		Developers, DevOps
Product	Product specs and requirements		Product Managers, Designers
Design	Design systems and guidelines		Designers, Developers
Operations	DevOps and infrastructure		DevOps, Developers
General	General knowledge and announcements		All

To add icon:

1. Click on the page icon (left of title)
2. Select emoji
3. Choose appropriate emoji

7.2 Create Sample Knowledge Items

Add a few test knowledge items:

curl -X POST http://localhost:8000/api/knowledge \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with Docker",
    "content": "Docker is a platform for developing, shipping, and running applications in containers...",
    "tags": ["docker", "devops", "tutorial"],
    "categoryId": "YOUR_ENGINEERING_CATEGORY_ID"
  }'

7.3 Test Relations

1. Open a knowledge item in Notion
2. Click on the Categories property
3. Select one or more categories
4. Open a category page
5. Verify the knowledge item appears in the Knowledge Items relation

---

Step 8: Configure Slack Bot (Optional)

If you're using the Slack bot integration:

8.1 Update Slack Bot Environment

Edit .env in the Slack bot directory:

# Slack Configuration
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_APP_TOKEN=xapp-your-app-token

# Backend API
API_BASE_URL=http://localhost:8000

# Server
PORT=3000

8.2 Test Slack Integration

1. Start the Slack bot:

npm start

2. In Slack, use the /knowledge command:

/knowledge add title:Test from Slack content:Testing Notion integration

3. Check Notion to verify the item was created

---

Troubleshooting Setup

Issue: "unauthorized" Error

Problem: API returns 401 unauthorized

Solutions:

1. Verify API key is correct in .env
2. Check for extra spaces or newlines in API key
3. Regenerate integration token if needed
4. Ensure integration is active (not deleted)

Issue: "object_not_found" Error

Problem: API returns 404 for database

Solutions:

1. Verify database ID is correct
2. Check database is shared with integration:
   • Open database in Notion
   • Click "..." "Connections"
   • Verify integration is listed
3. Try sharing again if not listed

Issue: Property Validation Errors

Problem: Creating pages fails with validation error

Solutions:

1. Check property names match exactly (case-sensitive)
2. Verify property types are correct
3. Ensure multi-select options exist in database
4. Check relation IDs are valid UUIDs

Issue: Empty Query Results

Problem: Queries return no results

Solutions:

1. Verify database has content (open in Notion)
2. Check integration has read permissions
3. Test with simple query (no filters)
4. Verify database ID is correct

Issue: Relations Not Working

Problem: Relations don't appear or fail to create

Solutions:

1. Verify relation property exists in both databases
2. Check both databases are shared with integration
3. Ensure relation is bidirectional (configured in both DBs)
4. Validate page IDs are correct UUID format

---

Verification Checklist

Before proceeding to use the integration, verify:

• [ ] Integration created and token saved
• [ ] All three databases created with correct properties
• [ ] All databases shared with integration
• [ ] Database IDs recorded and added to .env
• [ ] Backend environment configured
• [ ] API connectivity tested successfully
• [ ] Backend API endpoints working
• [ ] Test data created and visible in Notion
• [ ] Relations working between databases
• [ ] (Optional) Slack bot connected and tested

---

Next Steps

1. Read the Integration Guide: notion-integration.md
2. Review API Patterns: notion-api.md
3. Set up monitoring: Configure logging and error tracking
4. Add team members: Share databases with your team
5. Customize properties: Add custom properties as needed

---

Maintenance

Rotating API Keys

If you need to rotate your integration token:

1. Go to https://www.notion.so/my-integrations
2. Select your integration
3. Click "Show" under Internal Integration Token
4. Click "Regenerate" (if available) or create new integration
5. Update NOTION_API_KEY in backend/.env
6. Restart backend server

Adding New Properties

To add new properties to databases:

1. Open database in Notion
2. Click "+" in property header
3. Configure property
4. Update backend code to use new property:
   • Add to NotionPropertyMapper if needed
   • Update service methods (create/update/mapToArray)
   • Test thoroughly

Backup Strategy

Notion provides automatic backups, but consider:

1. Export databases regularly:

   • Settings Export Select databases
   • Choose Markdown & CSV format
   • Store exports securely

2. Version control:

   • Keep database schema documented
   • Track property changes in git
   • Document breaking changes

---

Support Resources

• Notion API Documentation: https://developers.notion.com
• Notion API Reference: https://developers.notion.com/reference
• Notion Community: https://www.notion.so/help/category/community
• Integration Issues: Check backend logs at backend/var/log/dev.log

---

Summary

You've successfully set up the Notion integration for Yappa Knowledge Hub. The system now has:

• Three interconnected Notion databases
• Proper authentication and permissions
• Backend services configured and tested
• Bidirectional sync capability

Your knowledge management system is ready to use!