Skip to content
DP-APIReviewed · 2026-11-19Desktop 1.8 · Companion 1.1.1Lire en français

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 ​

MethodRoutePurpose
GET/api/stateCalculated snapshot
GET/api/export.csvExport by kind: crafts, shopping, transactions, returns
POST/api/refreshReread sources
POST/api/settingsChange validated settings
POST/api/workspacePresentation preferences
POST/api/plan-previewCalculate a selection without saving
POST/api/planSave selections
POST/api/watchlistSave watched identifiers
POST/api/restockApply and save the suggested plan
POST/api/sessionStart, pause or confirm a step
POST/api/returns/batchApply decisions with scope and tokens
POST/api/returns/undoUndo the latest decision batch
POST/api/returns/reviewSave a price review
POST/api/returns/scenarioCalculate a relisting scenario
POST/api/returns/tsmPrepare TSM group import
POST/api/returns/companionPrepare Companion packet
POST/api/shutdownStop 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 ​

  1. Desktop → Companion: DP1: text containing an AceSerializer table, kind=DP_COMPANION and version=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.
  2. 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.
  3. Companion → desktop: DonjonsEtPognonsDB SavedVariables, 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.

A local-first advisor. Estimates stay visible.