The Customer API on Enshrouded
Drive your Enshrouded server from your own tools with the Customer API: settings, user groups, the map and players, the economy, chat and events, with scopes.
Before you start
You need an API key with the right scopes. Both work the same on every game:
- API Keys
- API Scopes
- Customer API โ base URL, authentication, errors, rate limits and paging
Every call below hangs off /api/public/v1/servers/{id}/. Starting, stopping, restarting, backups and files work exactly as on every other game, and are in the Customer API guide. This article covers what is specific to Enshrouded.
Settings and user groups
| Call | Scope | Notes |
|---|---|---|
GET settings | settings:read | Every setting. Group passwords come back masked |
GET settings/schema | settings:read | Ranges, options, and the difficulty-preset values for your server's own game build |
PUT settings | settings:write | Change values. The reply lists restart_required: those take effect at the next start |
GET settings/userGroups | settings:read | The group table, passwords masked |
POST settings/userGroups/table-secret | settings:write | One group's real password, on purpose |
The masking rule is worth understanding before you write user groups. A write sends the whole list. A group whose password is still the mask keeps its stored password, matched by name, so you can change a group's permissions without knowing its password. A new group sent with a mask and nothing behind it is rejected with an error naming the field, rather than being created with an empty password that would let anybody in.
Groups are checked on write: unique names, unique passwords (two groups with the same password, or two with none, are refused with the groups named and never the password, because Enshrouded will not start with them), known columns, and reserved slots no higher than your slot count.
POST settings/userGroups/table-secret is the deliberate exception that returns one password. Every call is recorded in your audit history (that it happened, never the value).
The three Inventory & Storage settings (stackSizeMultiplier, backpackExtraSlots, storageSlotMultiplier) are in the same calls as every other setting. See Bigger Stacks, Backpacks and Chests.
The world map and players
| Call | Scope | Returns |
|---|---|---|
GET map/capabilities | map:read | What the map can show for this server, including whether live player positions are available |
GET map/world | map:read | The map's state (ready, stale and so on), its build id, geometry and what is drawn on it |
GET map/world/tile?z=&x=&y=&build= | map:read | One tile image, with an ETag. Send it back as If-None-Match and an unchanged tile is a 304 |
GET map/world/layers?build= | map:read | Places with their in-game names, regions, and the spoiler layers (quests and placed loot) |
GET map/players | map:read | Who is online and where, from the server module |
GET map/share | map:read | Whether a share link is live and until when. Never the link itself |
Pin the build you were given by GET map/world when caching tiles. The map is published per game build, and a build that is no longer served answers 409, so read map/world again.
The spoiler layers are off by default in the panel. If you show the map to players, keep them off too.
Share links cannot be created or revoked through the API: they are owner actions in the panel.
The economy
| Call | Scope | Returns |
|---|---|---|
GET economy/status | economy:read | Whether purchases are open, and the delivery queue's figures for this game |
GET economy/catalog | economy:read | Items with the names players see, categories, stack sizes and prices |
GET economy/shop | economy:read | Your shop rows |
POST economy/shop | economy:admin | Add a shop row |
PUT economy/shop/{itemId} | economy:admin | Edit a row, including maxPurchaseQty |
DELETE economy/shop/{itemId} | economy:admin | Remove a row |
GET economy/wallet, GET economy/links | economy:read | Balances and who is linked |
POST economy/purchase | economy:write | Buy for a player. On Enshrouded the answer carries the order's place and estimated time in the delivery queue |
GET economy/kits, POST economy/kits/claim | economy:read, economy:write | List kits, claim one |
POST economy/award | economy:admin | Give a player currency |
GET economy/transactions | economy:read | Purchases and their delivery state |
POST economy/transactions/{txId}/retry, .../refund | economy:admin | Settle a delivery that stopped part way. A retry sends only what has not arrived; when the count of what arrived is not known it answers 422 confirmation_required until the request carries confirmFullResend: true, and when everything arrived it answers 409 state_conflict |
GET economy/chat | economy:read | In-game chat lines |
GET economy/chat/bridge, PUT economy/chat/bridge | economy:admin | The webhook chat bridge (below) |
The catalogue supports search, category and paging. Internal item names never leave the platform: you get the game's English names.
Lists come a page at a time. economy/shop and economy/catalog answer pagination with total, page, limit and has_more. economy/links, economy/transactions and economy/events answer { data, pagination: { has_more, next_cursor } }, newest first: pass next_cursor back as ?cursor= for the next page. Links take ?discord_user_id= to return one Discord user's links only.
One thing the API can do that the panel cannot: set maxPurchaseQty, a cap on how many of one item a player may buy in a single purchase. The panel has no field for it.
A purchase that is still being delivered cannot be refunded until it finishes or stops. See How Items Are Delivered on Enshrouded.
Settings events and presets
| Call | Scope | Returns |
|---|---|---|
GET config-presets/library | config_events:read | The ready-made presets, including one per difficulty preset with your build's values |
GET config-presets, POST config-presets | config_events:read, config_events:write | Your own presets; add one |
GET config-events, POST config-events | config_events:read, config_events:write | Scheduled events; schedule one, with restartWarningMinutes and startWhenEmpty |
GET config-events/warning-channels | config_events:read | Where players are warned. For Enshrouded inGame is false and suggestStartWhenEmpty is true |
GET config-events/restart-notices | config_events:read | The restart warnings sent recently, which the Discord bot posts to your alert channel |
warning-channels is worth calling before you schedule anything that interrupts players: it says plainly that in-game warnings are not available on this game.
GET config-events answers { data, pagination: { has_more, next_cursor } }, newest start first, instead of a bare list: read data, and pass next_cursor back as ?cursor= for older events.
What is not on the API
No teleport and no give. Both are panel actions only, from the live map, as on DayZ. The reasoning is in The GameGrid Discord Bot on Enshrouded.
No console command route, because the server accepts no commands.
No chat into the game. There *is* a POST economy/chat route, for games whose servers can show players a message. On Enshrouded it answers `capability_unsupported` with the reason, because the game gives a server no way to post into chat. GET economy/chat says the same with toGame: false.
Two ways to get chat out, and do not run both
GET economy/chat is the polling route. There is also a webhook chat bridge (economy/chat/bridge, economy:admin): the platform posts in-game chat to a Discord webhook by itself, with nothing of yours polling. The webhook URL is write-only: a read tells you only whether one is set.
It is an alternative to inviting the GameGrid Discord bot and running /chat-link. Pointing both at the same channel posts every message twice. Pick one.
A sensible first integration
If you are building something, this order gets you a useful result quickly:
1. GET settings/schema to learn what your server accepts, including its ranges.
2. GET economy/catalog to build your own shop list.
3. GET map/players on a timer for a live presence display. Positions update every couple of seconds, so polling faster than that gains nothing.
4. GET economy/chat for a chat feed of your own.
Keep an eye on the rate limits and error codes in Customer API, and use Webhooks rather than polling where you can.