Notion API Integration Guide

Originally written as internal engineering notes while building the thing it describes. Republished here with light editing — the timeframe is noted where it matters.

The project. The AI Hackathon Assistant is the event Q&A assistant built for the Aotearoa AI Hackathon Festival — a site participants use to ask questions about the event. Its FAQ needed to be editable by organisers who don't deploy code, and rankable by the participants reading it. Notion turned out to be the right backend for exactly that combination: the organisers already live in it, and it gives you a database with a REST API for free. The codebase was later generalised into an open-source template, event-qa-ai-template.

What follows is that integration in full — and it generalises to any read-mostly, human-edited content set with light write-back.

Table of Contents#

• Overview
• Architecture
• Database Schema
• API Routes
• Client-Side Implementation
• Caching Strategy
• Setup Instructions
• Troubleshooting

Overview#

The Notion integration serves as the backend for the FAQ voting and statistics system. It provides:

• Persistent FAQ Storage: Questions and answers stored in Notion database
• Community Voting: Upvote/downvote tracking with real-time updates
• View Analytics: Track question popularity via view counts
• Graceful Fallback: Static questions when Notion is unavailable

Key Benefits#

Architecture#

System Architecture Diagram#

Data Flow Sequence#

Database Schema#

Notion Database Properties#

Property Details#

Available Categories#

API Routes#

GET /api/faq/questions#

Fetches all active FAQ questions with their statistics.

Request: No body required

Response:

{
  success: boolean;
  questions: PresetQuestion[];  // FAQ content
  stats: FAQStats[];            // Vote/view statistics
  source: 'notion' | 'static' | 'static-fallback';
  timestamp: number;
}

Behavior:

• Queries Notion with filter: IsActive = true
• Returns fallback static questions if Notion fails
• Calculates score as upVotes - downVotes

POST /api/faq/vote#

Records an upvote or downvote for a question.

Request:

{
  questionId: string;
  voteType: 'up' | 'down';
  previousVote?: 'up' | 'down' | null;
}

Response:

{
  success: boolean;
  message: string;
}

Behavior:

• Finds page by QuestionID
• Removes previous vote if switching
• Updates UpVotes or DownVotes property
• Supports vote toggling (same vote = remove)

POST /api/faq/view#

Increments the view count for a question.

Request:

{
  questionId: string;
}

Response:

{
  success: boolean;
  message: string;
}

Behavior:

• Silent failure (doesn't throw on error)
• Non-blocking to user experience
• Increments TotalViews property

Client-Side Implementation#

Key Files#

Type Definitions#

// From components/chatbot/types.ts
 
interface PresetQuestion {
  id: string;
  question: string;
  answer: string;
  category: 'event-info' | 'teams' | 'technical' | 'schedule'
          | 'mentors' | 'awards' | 'logistics' | 'general';
}
 
interface FAQStats {
  questionId: string;
  upVotes: number;
  downVotes: number;
  totalViews: number;
  score: number;  // Calculated: upVotes - downVotes
}
 
interface FAQVote {
  questionId: string;
  vote: 'up' | 'down' | null;
  timestamp: number;
}
 
interface EnhancedPresetQuestion extends PresetQuestion {
  stats: FAQStats;
  userVote?: 'up' | 'down' | null;
}

useFAQVoting Hook#

const {
  isLoading,           // Loading state
  error,               // Error message if any
  enhancedQuestions,   // Questions with stats and user votes
  voteOnQuestion,      // Function to vote
  incrementViews,      // Function to track view
  getUserVote,         // Get user's vote for a question
  stats                // Raw stats data
} = useFAQVoting();

Optimistic Updates#

The voting system uses optimistic updates for instant UI feedback:

1. User clicks vote button
2. UI updates immediately (optimistic)
3. Vote saved to localStorage (privacy)
4. API call made in background
5. No rollback on failure (best effort)

Caching Strategy#

Client-Side Caching#

Cache Invalidation#

• Cache expires after 5 minutes (TTL)
• Manual invalidation via clearFAQCache()
• Fresh fetch on vote submission

Implementation#

// From lib/notion-faq.ts
 
const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
 
let questionsCache: { data: PresetQuestion[]; timestamp: number } | null = null;
 
export async function fetchFAQQuestions(): Promise<PresetQuestion[]> {
  if (questionsCache && Date.now() - questionsCache.timestamp < CACHE_DURATION) {
    return questionsCache.data;
  }
 
  const response = await fetch('/api/faq/questions');
  const data = await response.json();
 
  questionsCache = { data: data.questions, timestamp: Date.now() };
  return data.questions;
}

Setup Instructions#

1. Create Notion Integration#

1. Go to Notion Integrations
2. Click "New integration"
3. Name it (e.g., "AI Hackathon FAQ")
4. Select the workspace
5. Copy the Internal Integration Token

2. Create FAQ Database#

1. Create a new Notion database
2. Add the following properties:

3. Add select options for Category:

   • event-info, teams, technical, schedule, mentors, awards, logistics, general

4. Share the database with your integration

3. Get Database ID#

1. Open the database in Notion
2. Copy the URL: notion.so/{workspace}/{database_id}?v=xxx
3. Extract the database_id part

4. Configure Environment Variables#

Add to .env.local:

NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxx
NOTION_FAQ_DATABASE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

5. Populate Initial Data#

Add FAQ entries to the Notion database:

• Set IsActive to true for visible questions
• Use unique QuestionID values
• Initialize vote counts to 0

Troubleshooting#

Common Issues#

Debug Mode#

Enable debug logging by checking the API response:

const response = await fetch('/api/faq/questions');
const data = await response.json();
console.log('Source:', data.source);  // 'notion' or 'static-fallback'

Verify Notion Connection#

# Test API endpoint
curl http://localhost:3000/api/faq/questions

Expected response should include "source": "notion".

Related Documentation#

• UI Design System - Visual design guidelines
• CLAUDE.md - Main project documentation

Last updated: December 2024