Scope & Stability

Every API documentation page has an unspoken promise at the top. “Here are the endpoints. We have thought carefully about them. They are stable. If you build against them, your code will keep working.” That promise is worth reading critically because it’s almost always a little bit of a lie. Most APIs move. Endpoints get renamed. Response shapes change shape. Fields get added, removed, or quietly re-meaninged. The bigger the product, the more unstable the surface, because the surface is being shaped to serve the product’s evolution rather than the scripts people built on top of it. This page is the honest version of what Ishvana’s API does and does not promise. Read it before you sink a weekend into a tool that depends on the API surface staying still.

What this API is

A local FastAPI application that ships inside the Ishvana desktop app as a child process. When you launch Ishvana, Electron spawns the Python backend. When you close Ishvana, the backend stops. It only exists while the app is running, it only listens on localhost:37737, and it only talks to one client — your Ishvana desktop app — unless you point another client at it yourself.

It is:

Real HTTP. You can hit it with curl, Python, JavaScript, Rust, whatever speaks HTTP.
Real JSON. Request and response bodies are JSON. No custom binary protocols, no proprietary framing.
Real OpenAPI. The schema is auto-generated by FastAPI from Pydantic models. The live /openapi.json endpoint is authoritative.
Local-only by default. The backend binds to localhost and is not reachable from other machines on your network without explicitly reconfiguring it. Your data stays on your machine.

What this API is not

A few things to be clear about, because confusion on any of these would lead to bad decisions.

It is not a public API. Ishvana does not publish a hosted API at api.ishvana.com. There is no cloud backend. The only API you can talk to is the one running locally on your own machine while your desktop app is open. Scripts that try to hit a public URL will fail because there is no public URL.

It is not authenticated. There are no API keys, OAuth tokens, or bearer credentials. The assumption is that anything that can reach localhost:37737 is already running on the same machine as your Ishvana app, and anything on the same machine can already read your data directly through the filesystem. Adding authentication would not protect against any real threat model. (If you expose the backend to a wider network — don’t — authentication becomes critical. This is not a supported configuration.)

It is not versioned in the REST sense. The OpenAPI document has a version field (currently 5.0.0-ascension), but there is no URL-based API versioning. There’s no /api/v1/, /api/v2/, etc. When the API changes between Ishvana releases, the single URL path changes too. Old scripts that hit the old URL will fail against the new release.

It is not a published contract. The endpoints, request shapes, and response shapes are designed to serve Ishvana’s desktop UI, not to serve external consumers. They can change any time a feature gets refactored, redesigned, or rewritten. They have changed. They will change again. Building on top of this API means accepting that your code might need updates when Ishvana updates.

Stability in practice

That said, in practice the API is more stable than the disclaimers above might suggest, because most of its surface maps to features that don’t change shape much from release to release. A character entry is still a character entry. A document save is still a document save. A consistency check is still a consistency check. The fields on the request and response models might get new additions, but removing or renaming fields is rare and almost always tied to a substantial UI refactor.

Here’s the practical reliability tier you can expect across different kinds of endpoints:

Stability tier	Which endpoints	What this means
Relatively stable	CRUD on core entities — Legendry entries, documents, outline nodes, plotlines	Unlikely to change between minor versions. Scripts that use these tend to keep working.
Moderately stable	Workflow endpoints — Lorekeeper checks, Hawken generation, research pipelines	Response shapes evolve when features get upgraded. Core structure stays recognizable.
Unstable	Agent orchestration, experimental features, ML endpoints	Subject to change between releases. Don’t build critical automation against these.
Internal-only	Endpoints that aren’t documented here	Might exist for UI plumbing and might change without notice. If it’s not in the spec, treat it as gone.

Scripts that hit the relatively-stable endpoints can usually survive version upgrades with no changes. Scripts that hit the unstable endpoints might need updates every couple releases. The OpenAPI spec is regenerated per release, so if you dump openapi.json from each version you install, you can diff them and see what changed.

Breaking changes

The Ishvana team makes a few loose commitments about breaking changes even though there’s no formal stability guarantee:

No silent data loss. If an endpoint’s behavior changes in a way that could destroy existing data (delete entries, rewrite files, etc.), the old behavior is either preserved under a different endpoint name or flagged clearly in the release notes.
Feature removal is rare. Endpoints that exist because a feature exists tend to stay as long as the feature does. If a feature gets removed, its endpoints go with it, but the feature itself won’t silently disappear without users being told.
Response shape additions are fine. New optional fields in responses won’t break well-written clients. If your client ignores unknown fields, you’re safe.
Response shape removals and renames happen, but are noted. If a field you were relying on goes away, it’ll be mentioned in the changelog for the release that removes it.
Request validation will get stricter over time. If an endpoint accepts sloppy input today (missing fields, string-instead-of-number, etc.), it might reject the same input in a future version. Code defensively.

None of these are hard promises. All of them are reflections of how the team tends to work. If you need hard guarantees for a commercial integration, you don’t have them — this API is not sold as a supported product.

Data safety

The single most important thing to know: most of these endpoints can modify your data, and there’s no automatic undo.

Endpoints that destroy or mutate data:

DELETE on any entity — lore entries, documents, outline nodes, plotlines, everything. Most DELETE endpoints are destructive and permanent.
POST or PUT that writes a document or lore entry. The new content replaces the old content. Version history exists for documents but is limited.
Workflow endpoints that trigger generation. These can create lots of new entities in your project if they run with broad scope.
Batch operations that process many entities at once. One bad script can burn through dozens of lore entries in a second.

If you’re experimenting with write operations, always:

Back up your data directory first. A simple copy of the data/ folder is enough. Keep a snapshot before any batch operation.
Use a throwaway project to develop. Create a fresh project specifically for testing scripts. Once you’re confident, run against your real project with a backup in place.
Read the response of every write operation. Don’t blindly chain calls. Check that each one succeeded before moving to the next.
Log what your scripts do. If something goes wrong, a log tells you which operations ran and which didn’t. Logs are the difference between “I can recover from my backup” and “I don’t even know which entries got hit.”

The team did not build the API assuming adversarial or careless consumers. If you trash your data with a script, that’s on you. The safety expectations are the same as running any script against any important data: be careful, test, back up.

When things go wrong

If the API returns an error, the response body contains a structured error object with a type, a message, and usually a detail section explaining what went wrong. FastAPI’s default error format is preserved — you’ll get HTTP status codes (400, 404, 500, etc.) with JSON error bodies. Read the error body, not just the status code. “400 Bad Request” with a detail of “missing required field: title” is different from “400 Bad Request” with a detail of “invalid character name pattern” and both are different from “400 Bad Request” with a detail of “endpoint disabled in this build.”

Bugs in the API itself get logged to the Error Tracking panel automatically. If something is failing consistently and you think it’s a backend bug, check Error Tracking first — it might tell you what the underlying exception was.

What’s next

Use Cases Concrete examples of what to build on top of the API and what to avoid.

API Reference overview Back to the introduction page.