Local API and exchange formats
This is an internal desktop API without a third-party compatibility guarantee. It listens only on loopback. Exchange formats are versioned separately from application versions.
HTTP session
The launcher receives /?key=…, a random 24-byte key encoded as hexadecimal. The server exchanges it for the ForgeSession cookie (HttpOnly, SameSite=Strict), then redirects to /. Forge is a legacy technical name. Never paste this URL into an issue.
GET /health is unauthenticated and returns technical identity, not financial data. Other routes require the session. POST requests require the exact origin and application/json; bodies are limited to 65,536 JavaScript characters. This is not a UTF-8 byte limit. Incorrect host, unauthenticated requests and incorrect origin are rejected.
Routes
| Method | Route | Purpose |
|---|---|---|
| GET | /api/state | Calculated snapshot |
| GET | /api/export.csv | Export by kind: crafts, shopping, transactions, returns |
| POST | /api/refresh | Reread sources |
| POST | /api/settings | Change validated settings |
| POST | /api/workspace | Presentation preferences |
| POST | /api/plan-preview | Calculate a selection without saving |
| POST | /api/plan | Save selections |
| POST | /api/watchlist | Save watched identifiers |
| POST | /api/restock | Apply and save the suggested plan |
| POST | /api/session | Start, pause or confirm a step |
| POST | /api/returns/batch | Apply decisions with scope and tokens |
| POST | /api/returns/undo | Undo the latest decision batch |
| POST | /api/returns/review | Save a price review |
| POST | /api/returns/scenario | Calculate a relisting scenario |
| POST | /api/returns/tsm | Prepare TSM group import |
| POST | /api/returns/companion | Prepare Companion packet |
| POST | /api/shutdown | Stop the engine |
Conceptual selection example: {"selections":[{"key":"recipe-key","quantity":1}]}. Keys and signatures come from the current snapshot; do not invent them from translated names. For complete request bodies, follow each route's AppStore handler: the code remains the executable contract.
POST /api/restock replaces saved selections with the suggested plan: it can overwrite a manual plan. Use /api/plan-preview for a non-persisting calculation.
Three separate channels
- Desktop → Companion:
DP1:text containing an AceSerializer table,kind=DP_COMPANIONandversion=1. Realm/faction/region and character scope, rows keyed by exact itemString. Export limits: 50 characters, 2,000 keys and 512,000 UTF-8 bytes. The plan expires after 24 hours; every price retains its own two-hour age limit. Dates more than five minutes in the future are rejected. - D&P → TSM: serialized groups and operations, manually imported into TSM. This is not the Companion packet. Blocked rows produce a zero posting cap; profiles and variants remain separate.
- Companion → desktop:
DonjonsEtPognonsDBSavedVariables, observer journal version 1. Available after the client saves, read as data, never executed.
Decoders bound depth, count and types. A rejected import must not replace a valid plan with partial data. See game handoff.
