API Documentation

Complete reference for the CivicNotes tRPC API. Build integrations, automate workflows, and extend functionality.

Quick Start

Get started with the tRPC client in your React application

// Import the tRPC client
import { trpc } from '@/lib/trpc';

// Use queries for fetching data
const { data: notebooks, isLoading } = trpc.notebooks.list.useQuery();

// Use mutations for creating/updating data
const createNotebook = trpc.notebooks.create.useMutation({
  onSuccess: () => {
    // Invalidate and refetch
    utils.notebooks.list.invalidate();
  }
});

// Call the mutation
await createNotebook.mutateAsync({
  title: 'My Research',
  emoji: '📚'
});

Authentication

Understanding authentication levels and session management

publicPublic

No authentication required. Available to all users.

protectedProtected

Requires authenticated user. Session cookie must be present.

adminAdmin

Requires admin role. Only project owners and admins.

Using Authentication

// Check authentication status
const { user, isAuthenticated, loading } = useAuth();

// Redirect to login if not authenticated
if (!isAuthenticated && !loading) {
  window.location.href = '/login';
}

// Access user information
console.log(user?.email, user?.role);

Authentication

User authentication and session management

auth.mequerypublic

Get the current authenticated user's information

Output:User | null

Example:

const { data: user } = trpc.auth.me.useQuery();

auth.logoutmutationpublic

Log out the current user and clear session cookie

Output:{ success: boolean }

Example:

const logout = trpc.auth.logout.useMutation();
await logout.mutateAsync();

auth.requestMagicLinkmutationpublic

Request a magic link email for passwordless authentication

Input:{ email: string, rememberMe?: boolean }

Output:{ success: boolean }

Example:

const requestLink = trpc.auth.requestMagicLink.useMutation();
await requestLink.mutateAsync({ 
  email: '[email protected]',
  rememberMe: true 
});

Data Types

Common data types used across the API

// User type
type User = {
  id: number;
  email: string;
  name: string | null;
  role: 'user' | 'admin';
  createdAt: Date;
  lastSignedIn: Date;
};

// Notebook type
type Notebook = {
  id: number;
  notebookId: string;
  userId: number;
  title: string;
  emoji: string | null;
  createdAt: Date;
  updatedAt: Date;
  sourceCount: number;
};

// Source type
type Source = {
  sourceId: string;
  notebookId: string;
  fileName: string;
  fileUrl: string;
  contentType: string;
  fileSize: number;
  extractedText: string | null;
  tags: string | null;
  createdAt: Date;
};

// Message type
type Message = {
  id: number;
  sessionId: string;
  role: 'user' | 'assistant';
  content: string;
  citations: string | null;
  createdAt: Date;
};