API Reference
Complete REST API documentation for LoreForge v0.4.0. Base URL: http://localhost:8250 (self-hosted) or https://loreforge.co/api (cloud).
Interactive docs
The API ships with auto-generated Swagger UI at
/docs and ReDoc at /redoc. Visit localhost:8250/docs for an interactive explorer with request/response schemas.
Authentication
When auth is enabled (
REQUIRE_AUTH=true), include an Authorization: Bearer <token> header with all requests. Obtain a token via POST /auth/login. Self-hosted instances with auth disabled do not require a token.
Auth
User registration, login, and account management. Only active when REQUIRE_AUTH=true.
POST
/auth/register
Create a new user account (email, password, display name)
POST
/auth/login
Log in and receive a JWT access token
GET
/auth/me
Get the current authenticated user's profile
POST
/auth/change-password
Change the current user's password
POST
/auth/forgot-password
Request a password reset email
POST
/auth/reset-password
Reset password with a token from the email
Worlds
Manage worldbuilding projects. Each world is an isolated namespace for entries, edges, maps, and settings.
GET
/worlds
List all worlds accessible to the current user
POST
/worlds
Create a new world (name, description, optional template)
PUT
/worlds/{world_id}
Update a world's name or description
DELETE
/worlds/{world_id}
Delete a world and all its contents
POST
/worlds/{world_id}/set-default
Set a world as the user's default active world
Entries
Core CRUD for lore entries. Supports filtering by type, status, tag, era, region, and full-text search.
GET
/entries
List entries with filtering (type, status, tag, era, region, search, world_id)
POST
/entries
Create a new entry (name, type, body, tags, status, era, region)
GET
/entries/{entry_id}
Get a single entry by ID with full details
PUT
/entries/{entry_id}
Update an entry (creates a revision snapshot)
DELETE
/entries/{entry_id}
Soft-delete an entry (moves to trash)
POST
/entries/{entry_id}/restore
Restore a soft-deleted entry from the trash
GET
/entries/search
Full-text search with BM25 ranking (FTS5 or tsvector)
Entry Images
Upload and manage images for entries. Set a hero image for display in lists and search results.
POST
/entries/{entry_id}/upload-image
Upload an image to an entry's gallery
GET
/entries/{entry_id}/images
List all images for an entry
DELETE
/entries/{entry_id}/images/{image_id}
Delete an image from an entry
POST
/entries/{entry_id}/images/{image_id}/set-hero
Set an image as the entry's hero image
Edges
Relationships between entries. Edges are bidirectional with optional labels and types.
GET
/edges
List all edges, optionally filtered by entry_id or world_id
POST
/edges
Create a new edge between two entries (source_id, target_id, label)
PUT
/edges/{edge_id}
Update an edge's label or type
DELETE
/edges/{edge_id}
Delete an edge
POST
/edges/discover
AI-powered edge discovery: suggest new relationships for an entry
Actions (AI)
AI-powered writing actions. All actions use canon entries as context. Supported actions: expand, summarize, contradictions, connections, dialogue, codex.
POST
/actions/{action}
Run an AI action on an entry (entry_id, optional instruction, optional model)
POST
/actions/{action}/stream
Run an action with SSE streaming response
POST
/actions/accept
Accept a generation and apply it to the entry
POST
/actions/reject
Reject a generation (discards the output)
Bulk Generate
POST
/generate
Bulk-generate multiple entries from a freeform prompt or structured request
Chat
Conversational AI chat that uses your canon as context.
POST
/chat/send
Send a chat message and get an AI response with canon context
POST
/chat/stream
Send a chat message with SSE streaming response
Writing Coach
POST
/coach/message
Send a message to the AI writing coach
GET
/coach/conversations
List coach conversation history
Names
POST
/names/generate
Generate culturally-consistent names based on a description and world context
Scenes
POST
/scenes/generate
Generate a prose scene set in your world
Consistency
POST
/consistency/check
Run a world-wide consistency audit across canon entries
Chapters
GET
/chapters
List all chapters in a world
POST
/chapters
Create a new chapter
GET
/chapters/{chapter_id}
Get a chapter by ID
PUT
/chapters/{chapter_id}
Update a chapter's title, body, or order
DELETE
/chapters/{chapter_id}
Delete a chapter
Novel Plans
GET
/novel-plans
List all novel plans in a world
POST
/novel-plans
Create a new novel plan
GET
/novel-plans/{plan_id}
Get a novel plan with beats and sections
PUT
/novel-plans/{plan_id}
Update a novel plan
PUT
/novel-plans/{plan_id}/beats
Update the beats for a novel plan
PUT
/novel-plans/{plan_id}/sections
Update the sections for a novel plan
Story Threads
GET
/threads
List story threads in a world
POST
/threads
Create a new story thread
PUT
/threads/{thread_id}
Update a story thread
DELETE
/threads/{thread_id}
Delete a story thread
Timeline Events
GET
/timeline-events
List timeline events in chronological order
POST
/timeline-events
Create a timeline event (date, description, linked entry)
PUT
/timeline-events/{event_id}
Update a timeline event
DELETE
/timeline-events/{event_id}
Delete a timeline event
Maps
POST
/maps/upload
Upload a map image
GET
/maps
List all maps in a world
DELETE
/maps/{map_id}
Delete a map
GET
/maps/{map_id}/pins
List pins on a map
POST
/maps/{map_id}/pins
Add a pin to a map (x, y, linked entry)
DELETE
/maps/{map_id}/pins/{pin_id}
Remove a pin from a map
Calendars
Custom fantasy calendar systems with configurable months, moons, and holidays.
GET
/calendars
List calendars in a world
POST
/calendars
Create a custom calendar
PUT
/calendars/{calendar_id}
Update a calendar's months, moons, or holidays
DELETE
/calendars/{calendar_id}
Delete a calendar
Quests
GET
/quests
List quests in a world
POST
/quests
Create a quest with linked entries
PUT
/quests/{quest_id}
Update a quest
DELETE
/quests/{quest_id}
Delete a quest
GET
/quests/{quest_id}/sessions
List session logs for a quest
POST
/quests/{quest_id}/sessions
Add a session log to a quest
Export
GET
/exports/json
Export world as JSON (entries, edges, settings, metadata)
GET
/exports/markdown
Export as Markdown files in a ZIP archive
GET
/exports/pdf
Export as formatted PDF with table of contents
GET
/exports/epub
Export as EPUB e-book
GET
/exports/docx
Export as Microsoft Word document
Import
POST
/import/json
Import from LoreForge JSON export
POST
/import/notion
Import from Notion export file
POST
/import/world-anvil
Import from World Anvil export
POST
/import/zip
Import from a ZIP of Markdown files
World Settings
GET
/settings
Get world settings (name, summary, genre, tone, style samples)
PUT
/settings
Update world settings
App Config
LLM provider configuration. Stored in the database and overrides .env values.
GET
/app-config
Get current LLM provider, models, and key status
PUT
/app-config
Update LLM provider, models, or API keys
Billing
Subscription management via Stripe. Cloud mode only.
GET
/billing/status
Get subscription status, trial info, and generation usage
GET
/billing/plans
List available subscription plans and pricing
POST
/billing/checkout
Create a Stripe Checkout session for subscription
POST
/billing/portal
Create a Stripe Customer Portal session for managing billing
Collaboration
POST
/worlds/{world_id}/invite
Invite a collaborator by email (role: editor or viewer)
GET
/worlds/{world_id}/collaborators
List all collaborators for a world
PUT
/worlds/{world_id}/collaborators/{collab_id}
Update a collaborator's role
DELETE
/worlds/{world_id}/collaborators/{collab_id}
Remove a collaborator from a world
POST
/worlds/{world_id}/transfer
Transfer world ownership to a collaborator
POST
/worlds/accept-invite
Accept a collaboration invitation via token
Telegram
GET
/telegram/status
Get bot status, username, and webhook info
POST
/telegram/setup
Register the webhook URL with Telegram
POST
/telegram/webhook
Webhook endpoint for receiving Telegram updates
Marketplace
GET
/marketplace
Browse published worlds in the community marketplace
POST
/marketplace/publish
Publish a world to the marketplace
POST
/marketplace/clone/{world_id}
Clone a published world as a starting point
POST
/marketplace/unpublish
Remove a world from the marketplace
Image Generation
POST
/entries/{entry_id}/generate-image
Generate an image for an entry using the configured image provider
Voice
POST
/voice/transcribe
Transcribe an audio file via Whisper STT
Presence
Real-time presence for collaborative editing.
POST
/presence/heartbeat
Send a heartbeat with current entry being edited
GET
/presence/online
Get list of currently online users
GET
/presence/editing/{entry_id}
Check who is currently editing a specific entry
Lore Notes
Threaded notes attached to entries for discussion and brainstorming.
GET
/lore-notes
List notes for an entry
POST
/lore-notes
Create a new note on an entry
POST
/lore-notes/{note_id}/reply
Reply to an existing note
DELETE
/lore-notes/{note_id}
Delete a note
Additional Endpoints
Eras
GET
/eras
List eras (time periods) in a world
POST
/eras
Create an era
Regions
GET
/regions
List regions in a world
POST
/regions
Create a region
Writing Stats
GET
/writing-stats/summary
Get writing statistics (word counts, sessions, goals)
POST
/writing-stats/goals
Set a writing goal
POST
/writing-stats/sessions
Log a writing session
Writing Prompts
GET
/prompts
List writing prompts (auto-generated from Telegram Q&A gaps)
Templates
GET
/templates
List available starter world templates
Stats
GET
/stats
Get world statistics (entry counts by type, edge counts, etc.)
Share
POST
/worlds/{world_id}/share
Generate a share token for presentation mode
Continuity
GET
/continuity/report
Generate a project-level relationship and continuity report
License
POST
/license/activate
Activate a self-hosted Pro license key
GET
/license/generate-trial
Generate a trial license for testing
Admin
GET
/admin/users
List all users (admin only)
GET
/admin/stats
Get platform-wide statistics (admin only)
Feedback
POST
/feedback
Submit user feedback
Health
GET
/health
Health check endpoint
GET
/models
List available models for the current provider