ChestAPI

A BepInEx plugin for the Valheim dedicated server that tracks every player-placed chest (any piece with a Container component) and exposes it over a local JSON HTTP API, so other services can answer questions like "do we have enough iron to build X?".

This is API-only: no UI, no in-game commands, just data.

AI-assisted development: This mod was written with the help of Claude Code, an AI coding assistant. I review the changes and run it on my own Valheim dedicated server, but it has not been tested across many setups or Valheim versions. If something breaks, please report it with your Valheim version and the ChestAPI lines from BepInEx/LogOutput.log. See the changelog for what has changed.

Installation

1. Install via Thunderstore (search "ChestAPI" under the Valheim community) using r2modman/the Thunderstore app on your dedicated server, or manually: drop ChestAPI.dll into <server>/BepInEx/plugins/ChestAPI/. Requires BepInEx (any mod manager install already includes it; manually, install the denikson-BepInExPack_Valheim pack first).
2. Set the API token in the environment the server process runs in, then (re)start the server:

   export CHESTAPI_API_TOKEN=$(openssl rand -hex 32)
   

   See "Configuring the token" below for details and alternatives.
3. Confirm it's up:

   curl -H "X-Api-Key: $CHESTAPI_API_TOKEN" http://127.0.0.1:8085/api/chests
   

What it tracks, per chest

• id — stable Valheim ZDOID (e.g. "1234567890:42")
• prefabName / displayName — e.g. piece_chest_wood / "Wood chest"
• position (x,y,z) and rotationEuler
• biome — best-effort (e.g. "Meadows")
• privacy — "Public" / "Private" / "Unknown" (best-effort)
• owner — placer's player id + name, if resolvable
• loaded — whether this came from a currently-active zone (fresh) vs. a periodic background scan of chests outside any loaded zone (see "How it works")
• width / height / usedSlots
• items[] — each with prefabName (use this for recipe matching), localized displayName, stack, maxStack, durability, quality, variant, crafterId/crafterName, grid position

Endpoints

All responses are JSON. Every request needs header X-Api-Key: <value> — there is no open/unauthenticated mode: with no token configured, the API denies every request (fails closed) rather than defaulting to allow.

A player chest is one that carries a creator id, meaning a player placed it. Dungeon and world chests (TreasureChest_* and similar) have none, so they only show up under /api/chests. Ships and carts that hold items also have a creator; leave them out with excludePrefab=Karve,VikingShip,Cart.

Choosing which chests

These work on every list, totals, count and check endpoint. Combine them freely; all of them must match. Names are case-insensitive, lists are comma-separated (or repeat the parameter), and an unknown parameter is a 400 rather than being silently ignored.

Map coordinates are Valheim world coordinates: x east-west, z north-south, y height.

Examples:

# How much iron do the player chests inside a 200 m circle around my base hold?
GET /api/playerchests/items/Iron/count?x=120&z=-2300&radius=200

# Ola's chests in a rectangle, without the item lists
GET /api/playerchests?owner=Ola&minX=0&maxX=500&minZ=-2500&maxZ=-2000&includeItems=false

# Can we build this? What is missing, and where is the rest?
GET /api/playerchests/check?need=Iron:150,Chain:20,Resin:300&area=base&where=true

Every totals, count, check and list response carries a Meta block: how many chests matched, how many are live (LiveChests) versus only known from the periodic scan (ScannedChests), and OldestUpdateUtc, the age of the stalest snapshot. A calculator can use it to say how fresh its numbers are.

Player names

Valheim only stores a chest's creator as a number, and the server only knows the names of players who are online. ChestAPI therefore remembers names: from players currently connected and from the crafter name stamped on any item in any chest. They are kept in BepInEx/config/mathias.valheim.chestapi.players.json and survive restarts. A player nobody has seen or whose crafted items are in no chest has no name yet; use their player id until they next log in.

Named areas

Define regions once on the server and let callers say ?area=base. In the BepInEx config, [Areas] Definitions, separate entries with ;:

base:circle:120,-2300,200;farm:rect:-300,100,-200,200

circle is x,z,radius; rect is minX,minZ,maxX,maxZ. Bad entries are skipped and logged at startup.

Configuring the token

Set it via the CHESTAPI_API_TOKEN environment variable in the environment the dedicated server process runs in (preferred — it never touches disk, so it won't end up in a config file or log):

export CHESTAPI_API_TOKEN=$(openssl rand -hex 32)

For a systemd-managed server, put it in the unit's EnvironmentFile= or an Environment= line so it's set before the process starts. If you'd rather use the BepInEx config file instead (BepInEx/config/mathias.valheim.chestapi.cfg, key ApiKey under [Http]), that works too, but the env var always wins if both are set. Restart the server after changing either.

How it works

The plugin tracks chests two ways. Live chests (anywhere a player currently is) update instantly whenever their contents change, via game hooks — this is where loaded: true comes from. Chests far from any player aren't normally kept in memory by the game at all, so a periodic background scan (every 60s by default, configurable) reads them directly from the server's saved world data instead; those show up as loaded: false. Either way, every chest the server knows about ends up in /api/chests — loaded just tells you whether the data is live or came from that last scan.

Chest location, in other words, doesn't matter — only whether somebody has to be standing nearby for the data to be fresh in real time.

For how this is implemented, build instructions, and known soft spots in the API detection, see DEVELOPMENT.md.

License

MIT.

Changelog

0.2.0

• New /api/playerchests endpoints that only look at chests players built, leaving out dungeon and world chests such as TreasureChest_*: the chest list, per-item totals, a single item's count, and a check endpoint that compares what you need against what you have and lists what is missing (and, with where=true, which chests hold it).
• Choose which chests to include with owner (player name or id), a map rectangle (minX/maxX/minZ/maxZ), a circle (x/z/radius), height, prefab, biome, item, loaded, or a named area. The same parameters also work on the existing /api/chests and item-count endpoints.
• New [Areas] config for naming regions, plus /api/areas and /api/players.
• Chest owners now get a player name even when offline: names are remembered in a small file next to the config. Previously PlayerName was null unless the owner happened to be connected.
• Responses carry a Meta block saying how many chests are live versus from the periodic scan, and how old the stalest snapshot is.
• Unknown or malformed query parameters now return 400 instead of being ignored.
• ChestDto gained PlayerPlaced. Existing fields and endpoints are unchanged, and /api/items/{prefab}/count still works (it still counts every container; use /api/playerchests/items/{prefab}/count for player chests).

0.1.3

• Fixed every request through a reverse proxy or tunnel failing with 400 Bad Request (Invalid host). Binding 0.0.0.0 now listens on all hostnames instead of only requests addressed to 0.0.0.0.

0.1.2

• Fixed the plugin failing to start on current Valheim dedicated servers: it tried to patch Container.OnDestroy, which no longer exists, and the resulting error stopped the HTTP API from ever starting. Chests that unload are now tracked without that patch.
• A hook that cannot be applied after a future Valheim update is now logged and skipped instead of stopping the whole plugin.

0.1.1

• Fixed the build failing on the Localization reference. Item display names are now looked up at runtime and fall back to the raw localization key if unavailable.
• Added the Thunderstore package icon.
• Known issue (fixed in 0.1.2): the plugin did not start on current Valheim servers.

0.1.0

• Initial release. This version was not published to Thunderstore because its build failed.