Customer API Reference

What the Customer API is for

The Customer API lets you build your own tools to manage your own game servers. Anything you can do to a server in the control panel - start it, change its settings, read its console, take a backup, install a mod - you can do from a script instead.

Build a Discord bot that restarts your server, a dashboard on a wall-mounted tablet, or a nightly job that backs up and reports. Everything lives under one address: https://wdcgamegrid.com/api/public/v1.

The API is RESTful, uses standard HTTP methods, returns JSON, and is versioned. Breaking changes go to /v2; new fields and new endpoints are not breaking.

`GET /openapi.json` is the reference that is never out of date. It is generated from the live routes, so it describes exactly what the server you are talking to can do. Point Postman, Insomnia or an SDK generator straight at it rather than transcribing this page.

Your first request

Put the key in an Authorization header and call any endpoint:

curl -H "Authorization: Bearer gsk_YOUR_KEY_HERE" \
https://wdcgamegrid.com/api/public/v1/servers

You get back a paginated list of your servers. The id field on each one is what every server-specific endpoint needs - save it.

A five-minute first script:

1. GET /account/keys/current - what your key can do. No scope required, so this works even if the scopes are wrong.

2. GET /account - who you are.

3. GET /servers - your servers, and their ids.

4. GET /servers/{id}/capabilities - what this particular server supports. Read this before calling anything game-specific.

5. GET /servers/{id}/realtime-stats - whether it is up, and how busy.

6. GET /servers/{id}/connection - what your players should actually type to join.

Steps 1 and 4 answer most "why did I get a 403 or a 501" questions before you have to ask. Get into the habit of reading capabilities first and calling only what they report true.

Authentication

Every request outside /meta/* and /openapi.json carries a bearer token holding an API key:

Authorization: Bearer gsk_XXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

A key is 56 characters: the prefix gsk_, an 8-character key id, an underscore, and a 43-character secret. The full key is shown exactly once, when you create it in the panel. The API never returns a secret again - GET /account/keys returns metadata only, and the 8-character key id is the safe identifier to log or display.

Keys are created, rotated and revoked in the panel, not through this API. There is deliberately no keys:write scope, so a leaked key cannot mint more keys. The one exception is keys:revoke, which lets a key switch itself off.

Cookies are ignored on this prefix. A browser session signed in to the panel gets a 401 here; the two authentication systems never overlap, and the API cannot be called cross-origin from a browser at all. Without a valid bearer token you get a 401, every time.

All authentication failures return the same 401 invalid_credentials - missing, malformed, unknown and wrong-secret keys are indistinguishable on purpose. The two exceptions are an expired key and a rotated key past its grace window, which return 401 token_expired.

See API Key Management for creating, scoping, rotating and revoking keys.

Finding a server, and telling people how to join it

GET /servers takes two filters so you do not have to pull every page and match in your own code:

Both combine with ?cursor= and ?limit=, and has_more and next_cursor describe the filtered list. Note that ?name= is charged at the search rate-limit tier, which is lower than read - use it to find a server once, not as a polling loop.

Every row also carries game: {slug, blueprint_version}, the same object GET /servers/{id} returns, so you do not need a call per server to find out which of yours are Valheim.

GET /servers/{id} also returns query_port: the port server browsers, status sites and query libraries ask for the name and player count. It is not always the game port plus one - each game declares its own - so read it rather than computing it. It is null for a game that has no separate query port.

The address your players type

GET /servers/{id}/connection is the one endpoint a status bot or a "join here" page needs:

{
"server_id": "...",
"state": "running",
"host": "203.0.113.9",
"game_port": 28000,
"public_address": "203.0.113.9:28000",
"join_code": null,
"join_code_known": true,
"connection_method": "direct",
"address_accepts_connections": true
}

Read connection_method before you show anything:

• `direct` - public_address is what players type. address_accepts_connections is true.
• `join_code` - the server is on a crossplay backend and nothing is listening on its game port. The six-digit join_code is the way in, and address_accepts_connections is false. Every Valheim server ordered with our defaults is in this state, so a bot that prints host:port unconditionally is printing an address that refuses connections.
• `unknown` - we could not reach the server host, so we do not know which of the two it is. join_code_known is false and address_accepts_connections is null. Show what you have and say it is unconfirmed; do not fall back to host:port, because that is exactly the case we could not rule out.

host is deliberately separate from public_address. Use host when you need the hostname on its own (an FTP client, a Steam query library) - do not split public_address on :, because on a crossplay server it carries the join code as well.

Capabilities - what each server can do

GET /servers/{id}/capabilities reports what this server actually supports, in eleven groups: lifecycle, console, logs, files, settings, players, backups, mods, maintenance, economy and map.

Games differ. A route can exist on the API and still be unsupported on your particular server - that returns 501 capability_unsupported, which is not an error in your code. Read capabilities first and call only what they report true, and you will not write handling for a 501 you could have avoided.

The economy group

Worth its own paragraph, because one of its flags has no other way of being discovered.

automaticDelivery: false is not an error state and does not fail a purchase. POST /economy/purchase succeeds, the wallet is debited and the transaction is recorded — and no item arrives, because a person delivers it. No game the platform hosts today reports it false once its economy is available, but it is the flag that tells you, so read it rather than assuming. If you are building a shop bot, read this flag and tell the buyer what to expect.

Every flag in the group follows a switch the customer can flip: on a game whose economy is carried by an add-on, all five are false until the add-on is installed. Windrose is the case today — its economy is provided by Windrose Plus, and switching that on is what turns the whole group true. Read capabilities per request rather than caching them for the life of a session.

Windrose does deliver automatically, so automaticDelivery is true there once Windrose Plus (which GameGrid installs on every Windrose server) has loaded. What differs on Windrose is *where* the item lands: on the ground at the player’s feet rather than in a backpack, because the character lives on the player’s own machine. The capability flags do not report that — see Economy Overview.

Errors - always the same shape

Every error, on every route, comes back like this:

{
"error": {
"code": "insufficient_scope",
"message": "This API key does not have the required scope.",
"request_id": "req_...",
"details": { }
}
}

Branch on `code`, never on `message`. Codes are stable and changing one is a breaking change. Messages may be reworded at any time. Quote request_id in a support ticket and we can find the exact request.

The Vault's codes

The Vault's routes (the vault group below) answer these as well, besides the codes above. The Vault's own codes are the same words the panel uses, so a client and the panel branch on the same code; the numbers a code carries are in details.

GET /meta/error-codes returns this catalogue as JSON and needs no key.

Rate limits

Every route sits in one of nine tiers. All windows are 60 seconds.

Two extra caps apply to API keys. Per-server control: one key can send at most 10 control commands to the *same* server per minute. Organization multiplier: all of an organization's traffic in a tier is capped at 2× the per-key limit.

Every response carries the current state:

Rejected requests still count against your budget, so backing off properly matters. Read Retry-After rather than retrying immediately.

GET /meta/rate-limits returns the tiers as JSON and needs no key.

Pagination

List endpoints use cursor pagination:

{ "data": [ ], "pagination": { "has_more": true, "next_cursor": "eyJ0Ijo..." } }

Pass the cursor back as ?cursor=... to get the next page. Keep going while has_more is true; next_cursor is null once it is false.

GET /account/audit is the exception: it defaults to 100 and allows up to 500, over a fixed 24-hour window.

Some cursor lists have their own page sizes, and they are newest first. Settings history and the event list (config-events) default to 100 and allow at most 100. Economy links default to 100 and allow at most 500. Economy transactions and game events (economy/events) default to 50 and allow at most 200; on those three economy lists a limit that is not a whole number of at least 1 falls back to the default instead of answering 422. The shop and the catalogue page by number instead (page and limit) and answer pagination with total, page, limit and has_more. GET /servers/{id}/economy/links?discord_user_id=... returns only that Discord user's links, and has_more and next_cursor describe the filtered list.

Not every list is paginated, and the shape varies. Endpoints that return a complete set - backups, files, mods, current players, bundles, mod search - include pagination with has_more: false and no cursor. Two endpoints return no cursor at all: GET /servers/{id}/logs returns pagination: null, and GET /servers/{id}/console/history omits the field entirely. Test for the field's presence rather than assuming it is there, and treat the cursor as opaque - do not build one by hand.

Current players can be a recent list, marked stale. If GET /servers/{id}/players cannot read the live list (the server is restarting, the game is still starting up, or its machine did not answer), it returns the last list it read live in the past 10 minutes with three extra fields: stale: true, as_of (when that list was read) and stale_reason (server_not_running, game_not_answering or host_unreachable). A live answer has none of them. With nothing that recent, the answer is 502 upstream_unavailable as before. A bot that shows player counts can show the stale list with its age, or wait for the next live answer.

Idempotency

Every POST, PUT, PATCH and DELETE accepts an optional Idempotency-Key header. Send a UUID you generate; anything that is not a valid UUID is rejected with 400 invalid_request.

It is optional everywhere but one route. Send it on anything you would not want done twice: creating a backup, the maintenance actions, mod installs, file and backup uploads. Without the header, a retry does the work again. Starting a new stats season (POST /servers/{id}/metrics/seasons) requires it, so a retried request can never start two seasons.

A stored response can be replayed for 24 hours. Only successful responses are stored - if a request failed, a genuine retry runs again rather than replaying the failure. Bodies are compared with key order ignored, so re-serialising JSON does not break a replay. A key is scoped to one route, so the same UUID cannot accidentally deduplicate a call against a different server, and the query string counts: DELETE .../files?path=a.txt and ?path=b.txt are two different requests. Asking for a stream ticket is never replayed: retrying it gives you a fresh ticket.

Destructive actions need typed confirmation

Four actions require you to type something before they run: reinstall, wipe, delete-savegames and update. (verify does not - repairing files is not destructive.)

Send the server's exact current name in a confirm field:

{ "confirm": "Community Survival" }

The comparison is exact - no trimming, no case folding. Get it wrong or leave it out and you get 422 confirmation_required, whose details name the action, the field, and the exact value expected:

{ "error": { "code": "confirmation_required", "details": {
"action": "wipe", "expected_field": "confirm",
"expected_value": "Community Survival",
"hint": "Send the server's exact current name in the `confirm` field." } } }

This is a deliberate speed bump that a script cannot pass by accident. Ownership is checked before the confirmation, so seeing the expected value in the error means you already had access to that server.

Live console and log streaming

Streaming takes two calls, because a browser EventSource cannot send an Authorization header.

1. Mint a ticket with your normal bearer token: POST /servers/{id}/console/stream-tickets (scope console:read) or POST /servers/{id}/logs/stream-tickets (scope logs:read). You get back a stream_url.

2. Open that stream_url with EventSource.

Tickets last 60 seconds and are single-use. Mint one per connection and do not cache them. A ticket is bound to one key, one server and one kind - a logs ticket will not open a console stream, and trying burns the ticket anyway. A ticket carries exactly the minting key's scopes, no more, so a stream leaves out players' chat lines for a key that may not read chat, as the history and tail do.

Console streams have no fixed lifetime and no concurrency cap; log streams have both. A console stream stays open until you disconnect, the source ends, or your client stops reading: a console client that falls about 2 MB behind gets error { error: "slow_consumer" } and should reconnect with Last-Event-ID. A log stream ends after 60 minutes with error { error: "stream_lifetime_reached" }. A log client that falls behind gets gap; one that stays about 2 MB behind for 30 seconds gets error { error: "slow_consumer" }. Since 8 October 2026 your account can hold up to 50 log streams open at once, and the next ticket or connection is refused with stream_limit_reached (429). Handle error and ordinary disconnects by minting a fresh ticket and reopening - because tickets are single-use, every reconnect needs a new one.

Field conventions

Use snake_case field names. Some answers also carry an older camelCase name beside the snake_case one, with the same value, so existing integrations keep working: progressPercent (read progress_percent), jobId (read job_id), and the camelCase fields of DayZ events, Discord server links, leaderboards and player access (read the snake_case twin). Request bodies on those routes, and on the economy routes, accept either spelling. The older names are marked deprecated in the OpenAPI document. One answer is still camelCase only: the mod install result's own fields (hashCheck, notice, warning). All timestamps are ISO 8601 UTC with milliseconds and a Z suffix, e.g. 2026-08-16T02:56:02.261Z. Durations end in _seconds; byte counts end in _bytes; percentages end in _pct.

Booleans are real booleans, never the strings "true" / "false". Some large integers arrive as JSON strings to avoid precision loss - parse them rather than assuming typeof === "number".

null means "no value", never zero. This matters most for player counts and metrics on a stopped server.

A player's key or playerKey (Metrics and DayZ routes) is an opaque handle, k- followed by 22 characters. It is the same every time for the same player, so you can store it, but it is private to your account: it is not a Steam or game ID, another account sees the same player under a different key, and a key from another account matches nothing. An older p- followed by 16 characters, saved before keys were made private, is still accepted.

Singular resources are returned bare. Collections are wrapped in data - see Pagination above for when pagination is present and when it is not.

What the API deliberately does not do

Some things are panel-only, on purpose. These are not missing - they were left out for a reason:

• Creating or deleting servers. Both change what you pay. That belongs somewhere a human clicks a button and sees the price.
• Spending money. Nothing in this API can trigger a payment, buy a slot or change a card.
• Creating API keys. No scope lets a key create another key, so a leaked key cannot make more.
• Moving servers between paid slots. Commercial state, same reasoning as creating servers.

You can still read your billing summary and the plan list. You just cannot spend from a script.

Discovery endpoints - no key required

These need no authentication at all. Use them to build clients and to check your assumptions against a live server:

Recent changes

• 2026-10-26: responses match the published document. Five of these change what you receive:
• GET /servers/{id}/files entries are { name, type, size, modified_at }; truncated: true (and pagination.has_more) means the folder has more than the 2000 entries listed.
• GET /servers/{id}/player-lists entries carry name (the same value as label, which stays).
• The billing-summary counts and backup size_bytes are numbers, not strings.
• Battle Royale round_day is a date (2026-09-24), not a timestamp.
• The DayZ held prizes total is everything owed, not just the 100 lines listed.

Also: dayz/sales?limit= must be a whole number (400 otherwise). A settings save changes the server's JAR only after the settings are written, and a JAR change that then fails shows in not_applied_keys and warnings. A kit-claim Idempotency-Key reused for a different player is 409 state_conflict (idempotency_key_reused). Plans carry billing_interval. The specification now documents restart_required and new_world_only as lists of keys (check their length, not their truth), the real player-row fields, and the 201 that the console command, settings rollback and maintenance actions answer.

• 2026-10-26: more lists page. The event list (GET /servers/{id}/config-events) now answers { data, pagination } instead of a bare list, so read data. Links, transactions, game events and settings history page with pagination.next_cursor (pass it back as ?cursor=), and links can be filtered with ?discord_user_id=. The shop and the catalogue now say has_more.
• Guild links, leaderboards, player access and the economy take snake_case, and a leaderboard can be sent back as you read it (2026-10-26). PUT /integrations/discord/guilds/{guildId}, the leaderboard routes, PUT .../metrics/player-access and every economy route that takes a body now take snake_case names: guild_name, board_key, public_command, live_positions, discord_user_id, item_asset_name and so on, inside a kit's items too. The camelCase names still work. The answers of the guild link, the leaderboards, player access and the economy configuration carry the snake_case names beside the camelCase ones; none is removed or renamed. You can PUT a leaderboard back exactly as a GET gave it (the fields only an answer has are ignored); a boardId in the body that is not the one in the path is 400 invalid_request. Sending the same field in both spellings with different values is now 400 invalid_request (details.reason is conflicting_spellings) and changes nothing. Before, PUT .../economy/config and PUT .../economy/chat/bridge quietly kept one of the two, and PUT .../economy/shop/{itemId} failed with a 500. The same value in both spellings is fine.
• DayZ events take snake_case, and an event can be sent back as you read it (2026-10-26). POST and PUT .../dayz/game-events take duration_minutes, selects.hot_zones, rewards.kill_bonus.per_player_cap and so on, with the camelCase names still working. You can PUT back an event exactly as a GET gave it. A temporary area takes visible_to (admin, members or public). The timed steps are edited in the panel: leave selects.timeline out and they are kept; a PUT no longer deletes them.
• Idempotency counts the query string. Reusing an Idempotency-Key on the same route with a different query (?path=a.txt, then ?path=b.txt) is now 409 idempotency_conflict instead of a replay of the first answer. A trailing slash no longer makes a second route.
• Stream tickets are never replayed. Retrying POST .../logs/stream-tickets or POST .../console/stream-tickets with the same key gives you a fresh ticket. They also work on a deactivated server now, like every other way of reading its logs.
• List rows no longer carry `created_at_cursor`. It was an internal field. Page with pagination.next_cursor.
• A log file's `size` is a number or `null`, never false.
• Mod refusals keep their meaning. Turning a mod on or off, or installing one, answers the actual reason (for example "re-pack it as a .zip") with a 400, 404 or 422, instead of a bare 404 or a 502.
• Four more error codes are listed in GET /meta/error-codes: self_service_off, section_not_shared, metrics_disabled, metrics_public_surfaces_off.
• New snake_case fields: progress_percent (migration status) and job_id (mod install), beside the older camelCase names.
• Renaming, copying or moving onto something that already exists no longer replaces it. POST /servers/{id}/files/rename, .../copy and .../move now answer 409 state_conflict with details.reason destination_exists and change nothing when the destination is already there. Send "overwrite": true in the body (it is optional, false by default) to replace it. Before, a move or rename replaced an existing file and a copy overwrote a file or merged into a folder without asking.
• The Valheim map leaderboard says how far it pages. total is the whole board; pageable_total is how many rows the cursor can reach and truncated is true when that is fewer. A cursor that is not one we handed out is 400 invalid_cursor instead of quietly starting again at page 1.

Endpoint groups at a glance

The API is organised into 31 groups totalling 307 operations. Counts are operations, not paths - one path like /servers/{id}/backups/{backupId} carries a GET, a PATCH and a DELETE.

For the full per-endpoint reference with request examples, response shapes, scopes and rate-limit tiers, use GET /openapi.json. It is generated from the live routes, so it is the one reference that cannot drift.