API Reference & Developer Cookbook — FleshNote Documentation

FastAPI REST Endpoints Catalog #

All endpoints accept POST requests with JSON payloads containing project_path.

Route Path	Router Module	Request Payload Model	Response Structure
`/chapters`	`chapters.py`	`{ project_path: str }`	`{ chapters: ChapterMetadata[] }`
`/chapter/load`	`chapters.py`	`{ project_path: str, chapter_id: str }`	`{ status: "ok", content: str, pov_character_id: str }`
`/chapter/save`	`chapters.py`	`{ project_path: str, chapter_id: str, content: str }`	`{ status: "ok", word_count: int, appearances: str[] }`
`/characters`	`characters.py`	`{ project_path: str }`	`{ characters: Character[] }`
`/character/create`	`characters.py`	`{ project_path: str, name: str, role: str, ... }`	`{ status: "ok", character: Character }`
`/locations`	`locations.py`	`{ project_path: str }`	`{ locations: LocationNode[] }`
`/entities/search`	`entities.py`	`{ project_path: str, query: str }`	`{ matches: ScoredEntityResult[] }`
`/knowledge/for-entity`	`knowledge.py`	`{ project_path: str, entity_id: str, pov_id?: str }`	`{ facts: KnowledgeFact[] }`
`/sync/apply`	`sync.py`	`{ project_path: str, diff_payload: SyncDiff }`	`{ status: "ok", backup_path: str }`

Electron Preload IPC Catalog (`window.api`) #

Methods available to React components through the Electron ContextBridge:

TypeScript Interface (src/preload/index.ts)

export interface FleshNoteAPI {
  // Workspace & Config
  selectFolder: () => Promise<string | null>;
  getProjects: (workspacePath: string) => Promise<ProjectSummary[]>;
  initProject: (payload: InitProjectPayload) => Promise<{ status: string; path: string }>;

  // Chapters & Prose
  getChapters: (payload: { project_path: string }) => Promise<Chapter[]>;
  loadChapterContent: (payload: { project_path: string; chapter_id: string }) => Promise<ChapterContent>;
  saveChapterContent: (payload: { project_path: string; chapter_id: string; content: string }) => Promise<SaveResult>;

  // Entities & Knowledge
  getCharacters: (payload: { project_path: string }) => Promise<Character[]>;
  getLocations: (payload: { project_path: string }) => Promise<Location[]>;
  getEntities: (payload: { project_path: string }) => Promise<LoreEntity[]>;
  appendEntityDescription: (payload: AppendPayload) => Promise<{ status: string }>;

  // Native Window
  minimizeWindow: () => void;
  maximizeWindow: () => void;
  closeWindow: () => void;
}

Developer Cookbook: Extending FleshNote #

Recipe 1: Adding a New Field to Characters

Update Schema in `backend/db_setup.py`: Add column definition to `CREATE TABLE IF NOT EXISTS characters (...)`.
Update Pydantic Models in `backend/routes/characters.py`: Add field (e.g. voice_pitch: Optional[str] = None) to CharacterCreate and CharacterUpdate.
Update React UI in `EntityInspectorPanel.jsx`: Add input component to the character edit mode form.

Recipe 2: Adding a Custom Context Menu Action in Editor

Register Button in `EntityContextMenu.jsx`:

<button onClick={() => onAction?.('addForeshadowMarker', { text: selectedText })}>
  Add Foreshadow Marker
</button>

Handle in `Editor.jsx`: Add case to handleAction switch statement to mount your custom popup modal.