API Reference
Most users of Ishvana will never read this section of the wiki. That’s fine — the app works without it, and the hand-drawn UI that makes up 99% of the product is designed to keep you from ever needing to think about what’s happening under the hood. But there’s a specific kind of user who opens a new tool and immediately asks “can I script this?” If that’s you, welcome. The rest of this section is for you.
Ishvana’s backend is a local FastAPI application that runs as a child process when you launch the app. It listens on http://localhost:37737 — no network exposure, no authentication tokens, no cloud roundtrip, just a real REST API on your own machine that your manuscript data flows through. Everything the desktop UI does is implemented as calls against this API, which means anything the desktop UI does is also something you can do yourself with a Python script, a curl command, or a custom tool that speaks HTTP. The API is the first-class interface; the desktop UI is one client on top of it.
This section of the wiki documents the API surface so power users can build things. It’s generated directly from the backend’s OpenAPI specification, so every endpoint, every request model, every response shape is guaranteed to match the running backend for the version of Ishvana you have installed. Below the hand-written pages (this one, Scope & Stability, and Use Cases) is the auto-generated reference — several hundred endpoints grouped by subsystem and sortable by HTTP method.
What you can do with it
Section titled “What you can do with it”A few concrete things people have built or could build:
- Bulk import lore. You have 300 character entries in a CSV from an older project and you want them in Ishvana as Legendry entries. A short Python script hits
POST /api/creative/lore/...once per character and the migration is done in a few minutes instead of hours of manual typing. - External automation. A shell script that takes a new writing session’s word count, hits the analytics endpoint, and posts the result to your personal Discord every day. Ishvana doesn’t need to know it exists. It’s just hitting the API.
- MCP servers. Someone writes an Ishvana MCP server so Claude Code can read your Legendry and run consistency checks against your draft. The MCP server is a thin wrapper over the HTTP API. Ishvana itself doesn’t need to change.
- Browser extensions. A browser extension that sends the current page’s content to Ishvana’s research browser analysis endpoint and creates a smart bookmark. One-click research from any tab in Chrome.
- Custom CLIs. A command-line interface for Ishvana that doesn’t require the Electron UI — useful if you’re writing over SSH, running on a server, or just prefer terminals over GUIs.
- Batch editorial passes. Run the Lorekeeper’s consistency check against every chapter in a book via a single script, aggregate the results, and produce a pre-submission audit that would take hours to do by hand.
- Custom integrations with other tools. Push Ishvana’s writing session data to Obsidian, Notion, or your own tools. Pull metadata from an external source and import it as lore entries. Anything that involves “move data between Ishvana and something else” is a good candidate for API scripting.
None of these are officially supported features in the sense that we guarantee they’ll keep working across Ishvana versions. But none of them are hard to write either, and the API is stable enough in practice that simple scripts tend to keep working across minor version updates.
What’s in this section
Section titled “What’s in this section”Below those, the auto-generated API Reference section lists every endpoint in the backend by tag (creative writing, lore, research, marketing, etc.). Each endpoint has its own page with the request/response schemas, parameter descriptions, example payloads, and the exact HTTP method.
The live interactive docs
Section titled “The live interactive docs”One more thing worth knowing. The FastAPI backend also serves its own interactive documentation at two URLs when Ishvana is running:
http://localhost:37737/docs— Swagger UI. Interactive interface where you can read the endpoint descriptions, type in request parameters, and execute the request live against your running backend. Good for exploring the API surface and testing endpoints before writing a script.http://localhost:37737/redoc— ReDoc. A different rendering of the same OpenAPI spec, focused on reading rather than interactive execution. Some people prefer its layout for long reference sessions.
Both are built into FastAPI, both work out of the box whenever Ishvana is running, and both are more up-to-date than this wiki if the running backend differs from the version the wiki was last generated against. Open them in a browser tab alongside the app and you have the full surface available without needing anything else.
A warning before you start
Section titled “A warning before you start”This is a real API and you can do real damage with it. It has endpoints that create, modify, and delete data in your Legendry, your manuscripts, your plot tracking, and every other part of your project. There’s no undo for most of these operations. The UI versions of the same actions have confirmation dialogs; the raw API calls don’t.
If you’re going to script against the API, always:
- Back up your data directory first.
data/is your whole project. Copy it somewhere safe before running any script that writes. - Start with read-only endpoints.
GETrequests don’t change anything. Get comfortable reading before you try writing. - Test against a throwaway project. Make a fresh project specifically for experimentation, run your script there first, verify the behavior, then run against your real project.
- Never share your scripts with destructive operations without warnings. If you write a migration script and publish it for other users, mark it clearly and make sure it logs what it’s about to do before it does it.
The API gives you the keys. Use them carefully.