StashSage for POE2

Browse trained models (collapsed by default)

League Category Segment

Importances are normalized per model. Values shown as percentages.

#	Feature	Importance

Does this sound like you?

• You pick up items that could be good, but aren't quite sure
• Your stash fills up with "I'll price this later" items
• Pricing through the in-game trade UI feels tedious, so you avoid it
• Typing mods, comparing rolls, and overthinking prices takes more effort than it's worth
• You don't need a perfect price - you just want a smart starting point
• One hotkey, instant comparable items, list it, and get back to mapping

The same pricing engine behind the Discord bot is available as a small HTTP API for your own tools and scripts. Send it copied item text, get back a value estimate, comparable listings, and the modifiers driving the price — the same payload the desktop app renders.

Getting access

Ask in Discord and we'll issue you an API key and the base URL. Keys are per-consumer — one can be revoked without affecting anyone else.

Authentication

Send your key on every request as an X-API-Key header, or as Authorization: Bearer <key>.

Rate limits

30 requests per 60 seconds per key (/predict and /predict-gui combined). Over the limit returns 429 with a retry_after_seconds field.

POST/predict

JSON request body:

Field	Type	Required	Notes
item_text	string	Yes	The full copied item text, exactly as pasted from the game (CTRL+C while hovering it).
league	string	No	Installed league ID or exact name (case-insensitive), e.g. forbidden-rites or runes-of-aldur — see GET /leagues for what's currently installed. Omitting it uses the server's configured default league. An explicit value that isn't installed is rejected rather than silently falling back — see errors.
source	string	No	Free-form label for your own usage tracking; does not affect the response. Use a short, stable slug for your client (for example poe2-companion).
channel_id	string	No	Discord channel id, if calling from a Discord context.
guild_id	string	No	Discord server (guild) id, if applicable; omit for DMs.

Example request

curl -X POST "$STASHSAGE_API_URL/predict" \
  -H "X-API-Key: $STASHSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item_text": "Item Class: Amulets\nRarity: Rare\n...", "league": "forbidden-rites", "source": "my-tool"}'

Example response — 200 OK

Trimmed; real responses include full modifier and neighbor detail.

{
  "request_id": "18a02c64be4a4b2f9927430956515957",
  "release": {
    "api_version": "0.5.15", "model_version": "0.5.15", "build_date": "2026-09-04",
    "training_data_as_of": "2026-09-03T14:06:02+00:00",
    "model_trained_at": "2026-09-03T14:32:16+00:00"
  },
  "league": { "id": "forbidden-rites", "label": "Forbidden Rites", "defaulted": false },
  "currency_conversions": {
    "divine_to_exalt": 394, "chaos_to_exalt": 40,
    "display": "1d = 394e,  1c = 40e"
  },
  "xgb": {
    "predictions": { "xgb": 3235.6 },
    "bucket": "High", "bucket_low": 1576.0, "bucket_high": 47280.0
  },
  "target_item": {
    "item_name": "Ghoul Touch",
    "mods": [ { "pattern": "+# to maximum Life", "value": 45, "display": "+45 to maximum Life" } ]
  },
  "knn": {
    "summary": { "count": 3, "median": 3100.0, "mean": 3180.5 },
    "neighbors": [
      {
        "item_name": "Ghoul Wrap",
        "price_exalts": 3100.0, "price_display": "3100e/78c/8d", "price_simple": "3100e",
        "mods": [ { "pattern": "+# to maximum Life", "value": 42, "display": "+42 to maximum Life" } ]
      }
    ]
  }
}

Response fields

The example above is trimmed. These are the blocks every 200 response carries. Fields may be added over time, so ignore keys you don't recognise rather than treating them as errors.

Field	Notes
request_id	Opaque id for this call. Include it when reporting a problem.
release.api_version	Version of the StashSage release serving the request. It tracks the overall release — today it mirrors model_version — and is not an independent response-contract version, so a bump does not by itself mean the schema changed.
release.model_version	Version of the published model bundle the server has loaded.
release.build_date	Date that release was built. This is the build date of the API and model bundle, not the cutoff of the market data behind the models — see model and data freshness.
release.training_data_as_of	When the market data behind this prediction was assembled, ISO 8601 UTC. This is the freshness signal to display — see model and data freshness. null when the model that answered has no usable timestamp.
release.model_trained_at	When that model was trained, ISO 8601 UTC. Usually minutes after training_data_as_of; the gap is training time, not data age. null when unknown.
release.build_commit, release.git_sha	Optional build identifiers, present only when the running deployment has them. Handy when reporting a problem; don't depend on them.
league	{"id", "label", "defaulted"} — the league this prediction was priced against. defaulted is true when the request omitted league and the server's configured default was used. See GET /leagues for the installed set.
currency_conversions	The rates this response's display strings were rendered with: divine_to_exalt, chaos_to_exalt (each a whole number of exalts), and a preformatted display line. Read currency conversions before using them for anything but display.
xgb.predictions.xgb	Model #1 point estimate, in exalts.
xgb.bucket, xgb.bucket_low, xgb.bucket_high	Value band the estimate falls into, with band edges in exalts. bucket_high is null for the open-ended top band.
target_item	The server's own parse of the item you submitted — name, matched modifier patterns with their values, and computed DPS for weapons. Worth checking when a prediction looks wrong: it shows exactly what the models saw.
knn.summary	count of comparable listings found, plus the median and mean of their prices, in exalts. median and mean are omitted — not null — when no neighbor had a readable price, so count is the only key guaranteed to be present.
knn.neighbors	The comparable listings themselves, nearest first (ascending distance from your item). See neighbor objects for the per-neighbor fields.
xgb_visual	Presentation-shaped copy of the estimate for the desktop overlay and Discord embeds: the same prediction, a bucket label prefixed with a colour block, and color_square. Mirrored to the top level as xgb_bucket, xgb_color_hex, and xgb_color_square. Read xgb instead — these are display sugar and change with the UI.
updates	Desktop-updater block, attached only when the deployment has an update manifest configured. Not part of the pricing contract; ignore it.

GET/leagues

Lists the installed leagues you can pass to /predict//predict-gui, and which one is the default. Same X-API-Key authentication as /predict; no request body.

{
  "default_league": "forbidden-rites",
  "leagues": [
    { "id": "forbidden-rites", "label": "Forbidden Rites" },
    { "id": "runes-of-aldur", "label": "Runes of Aldur" }
  ],
  "release": { "api_version": "0.5.17", "model_version": "0.5.17", "build_date": "2026-09-13" }
}

Only usable, fully-loaded leagues are listed — check here rather than hardcoding an id, since which leagues are installed (and which is default) can change between releases.

Neighbor objects

Each entry of knn.neighbors is one comparable listing. /predict and /predict-gui build neighbors with the same serializer, so these fields are identical on both endpoints.

Field	Always present	Notes
item_name	Yes	The listing's item name; an empty string when the source row carried no name.
price_exalts	Yes	The listing's price in exalts, as a number. null when the row had no readable price. This is the field to compute on.
price_display	Yes	The same price preformatted across all three currencies, "<exalt>e/<chaos>c/<divine>d" (for example 3100e/78c/8d), each rounded to a whole number using currency_conversions. null when the price is unreadable.
price_simple	Yes	Short form in whichever currency the listing was posted in, e.g. 8d or 3100e. null when the price is unreadable.
mods	Yes	The modifiers the neighbor was matched on: pattern (the normalized mod text, with # standing in for the value), value, and a rendered display. May be empty. Entries also carry a comparison against the same mod on your item when your item has it.
base_type, icon_url, base_category	No	Present only when the item name resolves to a known base in the icon manifest. Absent — not null — otherwise, so test for the key.
dps	No	Weapons only: the computed DPS figures for that neighbor.
stash_name	No	Present only when the source listing carried one.

Units

Every price and estimate in the response is a plain number of exalts (Exalted Orbs): xgb.predictions.xgb, the bucket edges, knn.summary.median, knn.summary.mean, and neighbor prices alike. Listings posted in divine or chaos are converted to exalts before training and comparison, so exalts are the single canonical unit throughout — there is no per-field currency to inspect. Use currency_conversions to render a value in another currency.

Currency conversions

The rates in currency_conversions come from the training-time sidecar of whichever league's model answered your request — they are not a live market feed, and they only move when that league is retrained and a new release ships. Because each installed league trains independently, the same item can convert at different rates in different leagues — always read currency_conversions from the response you got rather than caching a rate across leagues. They are exactly what every price_display and price_simple string in that same response was rendered with, which is why those strings are always internally consistent with each other. If you need a current divine or chaos price, take it from a live source and apply it to the exalt numbers yourself.

Model and data freshness

Listings are re-scraped and models retrained every few days, per category, and published with a StashSage release. Two timestamps in the release block describe the answer you just got:

• training_data_as_of — when the feature matrix behind this prediction was assembled from scraped listings. This is the one to show users.
• model_trained_at — when the model itself was fitted on that matrix, normally minutes later.

Both are per model, not per release: categories retrain independently, so an amulet and a bow answered by the same deployment can legitimately report different dates. Both are also upper bounds — scraping precedes the matrix build, so the newest listing in the training data is somewhat older than the stamp. Neither is an exact market cutoff, and neither should be presented as one.

Either can be null when the model that answered carries no usable timestamp; treat that as "unknown" and fall back to release.build_date, which remains a coarse upper bound on the age of everything in the release. The keys are always present, so null means unknown rather than unsupported.

Versioning and change notice

Because api_version follows the release rather than the response contract, don't use it to gate on schema changes. Build your client to tolerate added fields, and ask in Discord if you want notice ahead of a contract change — the API is best-effort, but we would rather warn integrators than break them.

Errors

Every error response is {"error": {"code", "message", "details"}, "release": {...}}. details is omitted when there is nothing to add; on the codes below it carries request_id. /predict-gui shares /predict's league selection, authentication, and rate limits, so the same codes apply to both.

Status	error.code	Meaning
400	bad_request	item_text is missing, empty, or could not be parsed as a valid item.
400	invalid_league	An explicit league value isn't installed, is retired, or is malformed — it never silently falls back to the default. Check GET /leagues for valid ids.
401	unauthorized	API key is missing, invalid, or revoked.
404	no_model	The item's category has no trained pricing model yet.
429	rate_limited	Too many requests for this key in the current window; see retry_after_seconds.
500	inference_failed	Prediction failed inside the model; include request_id when reporting it.
500	internal_error	Unhandled server-side failure. Carries no details, so quote the X-Request-Id header you sent when reporting it.
503	league_unavailable	league was omitted and the server has no valid default league configured (for example, multiple leagues installed with none chosen as default). Pass an explicit league from GET /leagues.

Interested in learning more about other DataWiseGuys projects? Check them out below.

Want to brainstorm developing your own app with analytics or machine learning? Reach out to us.