Use Cases

The API is real but it’s also specialized. Not every tool idea maps cleanly onto what Ishvana’s backend can do, and not every idea is worth the effort to build. This page walks through specific use cases that people have built or could build against the API, organized by what they’re good for. Each one includes enough detail that you can tell whether it’s worth your time before you commit to coding anything. None of them are official products — they’re examples of patterns that work. If you build something interesting against the API and want to share it, the Discord server is where that conversation happens.

Bulk data import

Problem: You have existing content somewhere else — a spreadsheet of character names, a Notion database of worldbuilding notes, a JSON export from another writing tool — and you want it in Ishvana’s Legendry as structured lore entries.

Why it’s a good fit for API: Because nobody wants to type 300 entries into a UI, one at a time. Bulk imports are the classic case where scripting wins over manual work.

Rough shape:

1. Parse your source data into a list of (title, entry_type, content) tuples.
2. For each tuple, call POST /api/creative/lore/ with the appropriate request body.
3. Handle errors per-entry. Don’t let a single bad row kill the whole import.
4. Log every created entry’s ID so you can audit or undo the import later.

Tools worth knowing: Python + requests is the standard setup. JavaScript + fetch works too. The request body shape is defined in the API Reference pages for the lore tag. The backend validates your payloads against Pydantic models so you’ll get clear error messages when the shape is wrong.

Gotchas:

• Entity detection doesn’t run automatically on imported content. If you want your imported characters to get detected in future prose, you might need to trigger entity extraction separately.
• Rate limiting isn’t a concern (it’s localhost), but the LLM-backed endpoints can run slowly if you’re doing auto-summarization as part of the import. A batch of 500 imports that each run a lore summary through Hawken can take hours and cost meaningful tokens.
• Your source data’s structure probably doesn’t map 1:1 to Ishvana’s schema. Expect to write a mapping layer.

MCP server for Claude Code

Problem: You’re using Claude Code for writing work and you want Claude to read your Legendry, run consistency checks on drafts you’re writing, and maybe even kick off research via Lagan — all without you having to context-switch to Ishvana’s UI.

Why it’s a good fit for API: Claude Code’s MCP protocol is designed for exactly this. An MCP server is a small process that exposes tools (functions Claude can call) backed by whatever data source you want. Ishvana’s backend is a perfect data source for MCP — real HTTP, clear schemas, local-only.

Rough shape:

1. Build an MCP server using the Anthropic MCP SDK in the language of your choice.
2. Expose tools like search_lore(query), get_entry(entry_id), check_consistency(document_id), run_research(query).
3. Each tool translates the call into an HTTP request against localhost:37737.
4. The MCP server runs as a background process alongside Claude Code.
5. Claude can now call into Ishvana’s knowledge base during any conversation.

Why this is the most valuable possible use case: Because it bridges two tools that are both designed well but don’t know about each other. Claude Code has the conversation and the reasoning. Ishvana has the world and the project data. Putting them together means Claude can answer questions like “does this scene I’m writing contradict anything in the Legendry” without you having to ferry data between them by hand.

Gotchas:

• Ishvana has to be running for the MCP server to work. If your agent tries to call when the backend isn’t up, the calls fail. Handle that gracefully in the MCP tool implementations.
• The backend’s endpoints are designed for a UI client, so some responses include UI-flavored metadata you don’t need. Strip it before returning to Claude to keep token usage reasonable.
• Consistency checks and research pipelines can be slow (they run LLM calls themselves). Claude might timeout waiting for them. Consider implementing the slow operations as “submit and poll” rather than synchronous calls.

Writing session analytics exporter

Problem: Ishvana’s writing analytics are good but stay inside Ishvana. You want to push your daily word count to your personal website, a Discord channel, a gamified habit tracker, or an external dashboard.

Why it’s a good fit for API: Because the analytics data is already structured and the push operation is trivially scriptable.

Rough shape:

1. Write a small script that hits GET /api/writing/analytics/session-history or similar.
2. Pull the current session’s word count, total words written this week, streak data, etc.
3. Format as needed and POST to your destination (Discord webhook, HTTP endpoint, JSON file, whatever).
4. Schedule it to run on a cron or via your OS’s task scheduler.

Tools worth knowing: Any language works. Discord webhooks are the easiest for personal updates. For something fancier, a small Vercel/Netlify function can receive the data and render a public dashboard.

Gotchas:

• Analytics endpoints might return more fields than you need. Project-level stats vs. document-level stats are different endpoints; pick the right one.
• The schema is one of the more likely to evolve between Ishvana releases because the analytics system is still being refined. Don’t build tight coupling to field names.

Browser extension for research capture

Problem: You’re on the web reading an article and you want to save it as an Ishvana research bookmark without switching apps.

Why it’s a good fit for API: Because Ishvana’s research module already has a smart bookmark endpoint that takes a URL, extracts content, runs analysis, and stores the result. A browser extension just needs to send the current tab’s URL and content to that endpoint.

Rough shape:

1. Build a minimal browser extension (Chrome or Firefox) with a single toolbar button.
2. On click, the extension reads the current tab’s URL and HTML content.
3. POSTs to http://localhost:37737/api/browser/bookmark with the captured data.
4. Shows a notification when the save completes.

Gotchas:

• Browser extensions can’t hit localhost from a page context without explicit permissions. You’ll need to configure the extension’s permissions to include http://localhost:*.
• Some pages are mostly JavaScript and have no meaningful HTML to extract. The extension should grab the rendered DOM, not the raw HTML, for those cases.
• If Ishvana isn’t running when you click the button, the request will fail. Show a user-friendly error.

Custom headless CLI

Problem: You want to interact with Ishvana from a terminal. Maybe you’re writing over SSH. Maybe you prefer terminal workflows. Maybe you’re automating something and don’t want to deal with windowing at all.

Why it’s a good fit for API: Because the backend works fine without the Electron UI. Start the backend manually (via the Python entry point), and you have an Ishvana that responds to HTTP requests without any GUI at all.

Rough shape:

1. Start the backend as a standalone process: uv run python -m backend.core.main (or whatever the current entry point is).
2. Write a Python CLI using click or typer that wraps common operations — ishvana lore list, ishvana doc save, ishvana lorekeeper check <file>.
3. Each command translates to an HTTP call against the running backend.
4. Package the CLI as a standalone tool and run it from anywhere.

Why this is real: The desktop UI is one client. The backend was built to serve it, but the architecture is genuinely client-server. Nothing stops you from writing a different client.

Gotchas:

• The backend’s startup time is not trivial (~10 seconds on first launch). If you’re running a quick command, you’d want to keep the backend running in the background and just make HTTP calls rather than starting the backend per command.
• Not every feature is fully usable without the UI. Some workflows (like the research browser) depend on the embedded browser that lives in Electron, and hitting those endpoints without the UI context might produce odd results.

Batch editorial audits

Problem: You’re finishing a book and you want to run Lorekeeper, ProseGuard, and style analysis against every chapter in one pass, then aggregate the results into a single pre-submission report.

Why it’s a good fit for API: Because the UI runs these checks one chapter at a time, and for a 20-chapter book that’s 20 clicks and 20 waits. Scripting runs them all at once and aggregates.

Rough shape:

1. List all documents in the current project via GET /api/creative/lore/documents/ (or whatever endpoint returns the full document list).
2. For each document, fire a consistency check, a ProseGuard lint, and a style analysis in parallel.
3. Wait for all responses.
4. Aggregate the results — counts per severity, top repeated issues, trend lines by chapter.
5. Output a Markdown report you can read in your editor or paste into a submission prep doc.

Gotchas:

• LLM-backed checks are slow. Running them in parallel speeds up the total wall-clock time but burns through tokens faster. Watch your cost tracking panel if you’re using cloud models.
• Consistency checks return structured issue lists, not just pass/fail. Your aggregation should group by issue type, affected entity, and severity to be useful.
• Some checks modify state (they persist the check results). Running them as part of an automation means your project will accumulate check history. Usually fine, sometimes not.

What probably isn’t worth building

A few use cases that sound appealing but map badly to what the API actually does:

A cloud sync layer. Ishvana is local-first. Trying to turn it into a cloud-synced product by hand-rolling sync against the API is a lot of work and the result would be fragile. If you want cloud sync, use a file sync tool (Dropbox, Syncthing, git) on the data directory.

A multi-user collaborative editor. Ishvana isn’t built for real-time collaborative editing, and the API doesn’t expose the primitives you’d need to build it (operational transforms, presence tracking, conflict resolution). Trying to shoehorn collaboration on top will fight the architecture.

A public-facing API gateway. Do not expose your local Ishvana backend to the public internet. There’s no authentication layer, and most endpoints can mutate your data. Exposing them puts your manuscript at the mercy of anyone who can hit the URL.

A web-based UI clone. You could, technically, write a web UI that talks to Ishvana’s local backend. But the desktop UI is polished and gets consistent updates — rebuilding it as a web UI would be a massive undertaking for uncertain gain. Better to use the desktop UI and script the edges.

What’s next

API Reference The auto-generated endpoint-by-endpoint reference for everything the backend supports.

Scope & Stability What the API promises and doesn't promise.

Engine The conceptual overview of the backend this API runs against.