GameServerKings API Reference

Endpoints

Orders

• POST /order/shared

  Order a shared game server

  Provisions a shared game server for the configured game, resources, and billing period, charging the selected payment method. Account credits are applied automatically and a fully credit-covered order is settled without a charge.

  Supply billableId to add the server to a subscription the caller already has instead of opening a new one, so both renew on a single invoice. The term, term discount and currency then come from that subscription and period is ignored. A subscription billed in advance is charged only for the part of the current period still ahead, as a prorated invoice due immediately; one billed in arrears is charged nothing at order time — the server is provisioned straight away and appears on that subscription's next invoice, prorated from the moment it actually went live.

  Authenticating with a TEST-mode API key runs the full validation and pricing path but does not create any order records, charge payment, or provision; the response includes test: true alongside a pricing breakdown instead of the created resource IDs.

• POST /order/dedicated

  Order a dedicated server

  Provisions a dedicated server for the configured type, disks, uplink, and billing period, charging the selected payment method. Account credits are applied automatically.

  Authenticating with a TEST-mode API key runs the full validation and pricing path but does not enqueue provisioning, charge payment, or persist anything; the response includes test: true alongside a pricing breakdown instead of the created resource IDs.

Game Servers

• GET /game/{idOrSlug}/configuration No auth required

  Get a game's shared-server configuration options

  Everything POST /order/shared will accept for one game: the compute, memory and storage tiers with this game's prices, the orderable game versions, the locations, the term discounts and the dedicated-IP price. The shared-server counterpart to /dedicated/types and /dedicated/locations.

  It is built from the same data as the public order page and priced the same way, so a configuration assembled from this response costs what the order page would charge for it.

  idOrSlug takes either the numeric game id or the slug from the game's public URL (/games/<slug>), so no id lookup is needed to call it.

  All prices are in USD cents per month. Within compute, memory and storage it is amount — not id — that the order endpoint expects for that category. defaults restates the tier amounts and version id the order page opens on, so it can be submitted as-is.

  Cached for 10 minutes, and cleared immediately when the game is edited.

• GET /shared

  List your game servers

  Returns all of the authenticated user's game servers (excluding deleted ones), each including its game and location, ordered by most recently created.

• GET /shared/{id}

  Get a game server by ID

  Returns details for a specific game server owned by the authenticated user, including its game, location, active plan(s), variant, the associated billing service (with its parent billable nested, if any), and the server's Pterodactyl UUID.

• POST /shared/{id}/configuration

  Change a shared server's plan

  Changes the compute/memory/storage tiers (and optional dedicated IP) of an existing shared game server, re-pricing the billable and charging the prorated difference for upgrades. Downgrades and same-price changes are applied without a charge. A configuration change cannot be started while another is pending, and is unavailable for subscription-style billables (FastSpring, internal, or Stripe/PayPal subscriptions).

  Authenticating with a TEST-mode API key runs the full validation and proration/pricing path but does not swap plans, create an invoice, charge, or re-provision; the response includes test: true alongside the computed proration, delta, and taxAmount.

Server Control

• GET /server/{id}

  Get a game server's panel detail

  Returns the panel's view of one game server — limits, feature limits, SFTP details, current lifecycle flags and the egg features that drive the console prompts.

  Every /server/{id}/* route is a proxy onto the Pterodactyl client API using a shared, admin-equivalent panel key, so access is gated first: the caller must have a linked panel account and be the panel-side owner of this server. Ownership is checked against the panel, not against our billing records, so managed-dedicated servers and anything else hosted for the customer work the same way. Anything that fails the check returns 404 rather than 403.

  Responses are field-filtered on the way out. The shared key sees more than a customer should, so each route carries an explicit allowlist and drops everything else.

• DELETE /server/{id}

  Delete a game server

  Deletes the server from the panel and releases the allocations it held.

  Deliberately narrow: this is allowed only for servers running on a node that backs a managed dedicated machine the caller owns — their own hardware, their own capacity. Shared hosting and anything else we bill for is refused with 403, because tearing those down belongs to cancellation rather than a button, and a server still attached to an uncancelled service is refused with 409.

• GET /server/{id}/resources

  Get current resource utilisation

  A single utilisation sample and the server's current power state. The same figures stream continuously over the console websocket, so this is for the first paint before that socket connects.

• GET /server/{id}/websocket

  Mint a console websocket token

  Returns a short-lived Wings token and the socket URL to open with it. The token carries the caller's permissions for this server and expires on its own, so a client is expected to call this again when Wings sends a token expiring event or the socket closes with an auth error.

  Only the token and socket URL are returned; the rest of the panel's response is dropped.

• POST /server/{id}/command

  Send a console command

  Writes one line to the running server's console. The server must be running — Wings rejects the command otherwise. Output is not returned here; it arrives on the console websocket.

• POST /server/{id}/power

  Send a power signal

  Starts, stops, restarts or kills the server. kill terminates the container immediately and can corrupt a save in progress, so treat it as a last resort after stop has been given time to finish.

  The signal is accepted asynchronously — the resulting state change arrives on the console websocket, not in this response.

• GET /server/{id}/activity

  List server activity

  The server's audit trail as the panel records it — power signals, file writes, subuser changes and so on, newest first. The originating IP address the panel stores against each entry is not forwarded.

• GET /server/{id}/files/list

  List a directory

  Lists one directory in the server's data volume. Paths are relative to the server root — / is the root itself. Directories are returned with is_file: false; there is no recursion.

• GET /server/{id}/files/contents

  Read a file

  Returns the file's raw bytes as text/plain, not JSON — this is the editor's read path. Large files and binaries are better fetched through the signed download URL instead.

• POST /server/{id}/files/write

  Write a file

  Overwrites the file at file with the raw request body, creating it if it does not exist. The body is sent as text/plain, not JSON, and the target path is a query parameter rather than part of the body.

• GET /server/{id}/files/download

  Get a signed download URL for a file

  Mints a short-lived URL pointing straight at the node, which the client then fetches directly. The file itself never passes through this API.

• GET /server/{id}/files/upload

  Get a signed upload URL

  Mints a short-lived URL the client POSTs a multipart form to, uploading straight to the node. Append ?directory=<path> to the returned URL to choose the destination directory. Uploads do not pass through this API.

• PUT /server/{id}/files/rename

  Rename or move files

  Renames each from to its to, both relative to root. Moving a file elsewhere is the same operation with a to that walks out of root.

• POST /server/{id}/files/copy

  Duplicate a file

  Copies the file at location alongside itself, with the panel choosing the copy's name. There is no destination parameter — rename afterwards to place it elsewhere.

• POST /server/{id}/files/create-folder

  Create a folder

  Creates name inside root. Intermediate directories are created as needed.

• POST /server/{id}/files/delete

  Delete files

  Deletes each entry in files from root. Directories are removed recursively, and deletion is not recoverable — there is no trash.

• POST /server/{id}/files/compress

  Compress files into an archive

  Packs the named entries in root into a .tar.gz written to the same directory, and returns the created archive's file object so a client can point the user at it. Large archives take a while; the panel returns once the archive exists.

• POST /server/{id}/files/decompress

  Extract an archive

  Extracts file in place inside root, overwriting anything already there with the same name.

• POST /server/{id}/files/chmod

  Change file permissions

  Sets the mode of each entry in files, relative to root. Modes are octal strings such as 644 or 0755.

• POST /server/{id}/files/pull

  Download a remote file onto the server

  Has the node fetch url into directory itself, so the file never passes through the browser. By default the transfer runs in the background and this returns as soon as the node has accepted it; set foreground to make the node hold the request until the download finishes.

• GET /server/{id}/databases

  List the server's databases

  Lists the MySQL databases attached to the server. Passwords are never included here — they are returned only by the create and rotate endpoints, at the moment they are minted.

• POST /server/{id}/databases

  Create a database

  Creates a database and a user for it, and returns the generated password — the only time it is shown in full. The panel prefixes the supplied name, so the created database's name will not match database verbatim.

  Refused by the panel once the server is at its feature_limits.databases cap, which is 0 on plans without databases.

• DELETE /server/{id}/databases/{databaseId}

  Delete a database

  Drops the database and its user. The data is not recoverable.

• POST /server/{id}/databases/{databaseId}/rotate-password

  Rotate a database password

  Generates a new password for the database user and returns it. The old password stops working immediately, so anything connecting with it — the game server's own config included — has to be updated.

• GET /server/{id}/network/allocations

  List the server's allocations

  The IP/port pairs assigned to the server. Exactly one is the primary (is_default), which is the address players connect to.

• POST /server/{id}/network/allocations

  Assign an additional allocation

  Takes the next free port on the node and assigns it to the server. There is no way to request a specific port. Refused by the panel once the server is at its feature_limits.allocations cap.

• GET /server/{id}/network/allocations/rules

  List Cosmic firewall rules per allocation

  Returns the Cosmic firewall rules that apply to each of the game server's allocations, keyed by the allocation id returned from /server/{id}/network/allocations.

  Rules are resolved per unique allocation IP and then filtered to those whose dst_port matches that allocation's own port, so on a shared protected IP the response only ever contains rules for the IP/port pairs this server actually holds — never another customer's.

  If rules for one IP cannot be fetched, that IP degrades to an empty rule list rather than failing the whole response, so an allocation may legitimately map to [].

• POST /server/{id}/network/allocations/{allocationId}

  Set an allocation's note

  Replaces the free-text note shown against the allocation. Send an empty string to clear it.

• DELETE /server/{id}/network/allocations/{allocationId}

  Release an allocation

  Returns the port to the node's free pool. The primary allocation cannot be released — make another one primary first.

• POST /server/{id}/network/allocations/{allocationId}/primary

  Make an allocation primary

  Promotes the allocation to the server's primary address. The change takes effect on the next start, since the running process is already bound to the old one.

• GET /server/{id}/backups

  List backups

  Backups are returned newest first. One with a null completed_at is still being taken; the console websocket announces the completion.

• POST /server/{id}/backups

  Create a backup

  Starts a backup and returns it immediately, before it has finished — completed_at is null until the node reports it done.

  Two limits apply and both come from the panel. The server's feature_limits.backups caps how many may exist at once (0 disables backups entirely), and the panel throttles how often they may be taken. A throttled request comes back as a 429 carrying the panel's own reason, which is safe to show the user verbatim.

• GET /server/{id}/backups/{uuid}

  Get one backup

  Returns a single backup, chiefly to poll whether it has finished.

• DELETE /server/{id}/backups/{uuid}

  Delete a backup

  Permanently removes the backup. A locked backup must be unlocked first.

• GET /server/{id}/backups/{uuid}/download

  Get a signed backup download URL

  Mints a short-lived URL pointing at the node holding the archive. The archive is not proxied through this API.

• POST /server/{id}/backups/{uuid}/lock

  Toggle a backup's lock

  Flips is_locked — this is a toggle, not a set, so the response is the authority on which way it went. A locked backup is exempt from rotation and cannot be deleted.

• POST /server/{id}/backups/{uuid}/restore

  Restore a backup

  Restores the archive over the server's files. The server is stopped for the duration and the console websocket refuses connections until the node reports the restore finished, so a client should expect the socket to drop and reconnect afterwards.

  truncate decides what happens to files that exist now: true wipes the volume first, so the result is exactly the backup; false unpacks over the top, leaving anything the backup does not contain in place.

  Like backup creation, this is throttled by the panel and a throttled request comes back as a 429 carrying the panel's reason.

• GET /server/{id}/schedules

  List schedules

  The server's cron schedules. Tasks are not included here — fetch a single schedule for those.

• POST /server/{id}/schedules

  Create a schedule

  Creates an empty schedule — a schedule with no tasks does nothing, so follow this with at least one task. The five cron fields are supplied separately and take standard cron syntax including *, ranges and steps; they come back joined under cron.

• GET /server/{id}/schedules/{scheduleId}

  Get a schedule and its tasks

  Returns the schedule together with its tasks in sequence_id order. This is the only route that returns tasks.

• POST /server/{id}/schedules/{scheduleId}

  Update a schedule

  Updates the schedule. POST, not PATCH, because that is what the panel exposes. Fields may be sent individually, but note that the panel rebuilds the cron expression from whatever it is given — send all five cron fields together when changing the timing.

• DELETE /server/{id}/schedules/{scheduleId}

  Delete a schedule

  Deletes the schedule and every task on it.

• POST /server/{id}/schedules/{scheduleId}/execute

  Run a schedule now

  Queues the schedule's tasks immediately, without waiting for its cron time and without altering the next scheduled run. Works even when the schedule is inactive.

• POST /server/{id}/schedules/{scheduleId}/tasks

  Add a task to a schedule

  Appends a step to the schedule. payload is interpreted by action: the console command for command, the power signal (start, stop, restart, kill) for power, and the ignored-files list for backup.

  time_offset is how long to wait after the preceding task before this one runs, which is why the first task in a schedule normally uses 0.

• POST /server/{id}/schedules/{scheduleId}/tasks/{taskId}

  Update a schedule task

  Updates any subset of the task's fields. POST, not PATCH, matching the panel.

• DELETE /server/{id}/schedules/{scheduleId}/tasks/{taskId}

  Delete a schedule task

  Removes one step from the schedule. The remaining tasks keep their order.

• GET /server/{id}/startup

  List startup variables

  The egg's configurable variables with their current values, plus the rendered and raw startup commands and the Docker images the egg offers.

  meta.docker_image is the image the server is actually running, which the panel's startup endpoint does not report — it is read from the server detail and merged in here so a client can mark the current choice in meta.docker_images.

• PUT /server/{id}/startup/variable

  Set a startup variable

  Sets one variable's value. key is the variable's env_variable, not its display name. The new value takes effect on the next start, and the panel refuses variables the egg marks is_editable: false.

• POST /server/{id}/settings/rename

  Rename the server

  Changes the server's display name in the panel. Nothing about the running server changes.

• POST /server/{id}/settings/reinstall

  Reinstall the server

  Re-runs the egg's install script against the existing volume. The server is stopped for the duration and is_installing stays true until it finishes; the console websocket reports progress.

  The install script may overwrite files it owns, so this is destructive for some eggs. Take a backup first.

• PUT /server/{id}/settings/docker-image

  Set the server's Docker image

  Switches the server to one of the images its egg offers — the keys of meta.docker_images from the startup endpoint. Commonly this is how a Java version is changed. The new image is used from the next start.

Dedicated

• GET /dedicated/template-groups No auth required

  List OS template groups and their templates

  Returns all template groups, each with its nested OS templates (id, profile id, and version). Response is cached for 1h.

• GET /dedicated/types No auth required

  List available dedicated server types

  Always returns each type's configurable options alongside the type metadata. Response is cached for 1h.

• GET /dedicated/locations No auth required

  List available locations

• GET /dedicated/benchmarks No auth required

  List benchmark scores for available dedicated types

  Returns benchmark categories, the dedicated types that have at least one score recorded, and the per (type, category) scores joining them. Only types currently marked available are included.

• GET /dedicated/inventory No auth required

  List dedicated server inventory

• GET /dedicated

  List your dedicated servers

  Returns all active dedicated servers owned by the authenticated user, each including its type and location, ordered by most recently assigned.

• GET /dedicated/{id}

  Get a dedicated server by ID

  Returns details for a specific dedicated server owned by the authenticated user, including type, location, options, and the associated billing service (if any).

• GET /dedicated/{id}/power

  Get a dedicated server's power status

  Returns the current power state of a dedicated server owned by the authenticated user, sourced from TenantOS.

• POST /dedicated/{id}/power/on

  Power on a dedicated server

  Requests a power-on for a dedicated server owned by the authenticated user via TenantOS.

• POST /dedicated/{id}/power/off

  Power off a dedicated server

  Requests a power-off for a dedicated server owned by the authenticated user via TenantOS.

• POST /dedicated/{id}/reinstall

  Reinstall a dedicated server

  Starts a reinstallation of a dedicated server owned by the authenticated user using the given OS template profile id. The profile id must map to a configured template; arbitrary TenantOS profiles are rejected.

Firewall

• GET /firewall/profiles

  List firewall profiles

• GET /firewall/{ip}

  Get firewall rules for an IP

• POST /firewall/{ip}

  Update firewall rules for an IP

  Replaces the firewall rules for the IP with the supplied set. An empty array clears all rules for the IP. The response returns the canonical rules after the update.

• GET /firewall/attacks

  Get DDoS attack history across the account

  Returns the paginated history of mitigated DDoS attack events recorded against the authenticated user's IPs, newest first.

  When addresses is omitted, results span every IP the user owns — those bound to their machines plus any attached directly to their account. When addresses is supplied, results are restricted to those IPs; if any requested address is not assigned to the user, the request is rejected with 400.

  History on a machine-bound IP starts when that machine was assigned to the account: attacks absorbed by the address under a previous tenant are not returned. IPs attached directly to the user account carry no such cutoff and return their full history.

• GET /firewall/metrics

  Get firewall traffic metrics for several IPs at once

  Returns the same time-bucketed filter metrics as /firewall/{ip}/metrics, for many addresses in a single request, keyed by address.

  Intended for a live fleet view. Polling the per-address route for every address costs one request and one rate-limit token each per refresh, for data that is a single windowed scan of the same table; this route is one of each however many addresses are involved.

  Every requested address must belong to the authenticated user. A single address that does not is rejected with 400 rather than being omitted, so a typo surfaces as an error instead of as an address that looks quiet.

  An address the caller owns but which saw no traffic in the window is present in the response with an empty array, so "quiet" is distinguishable from "not reported".

  Rate limited on the same buckets as the per-address route.

• GET /firewall/{ip}/metrics

  Get firewall traffic metrics for an IP

  Returns time-bucketed firewall/filter traffic metrics for one of the authenticated user's IPs, powering the live throughput and packet-rate charts in the client area. Data is aggregated per bucket and summed across mitigation nodes, ordered oldest to newest.

  This endpoint is rate limited per user (a token bucket of 20 requests refilling at 10/s) and globally; when exhausted it responds with 429 and a Retry-After header (seconds).

  To follow several addresses at once, prefer GET /firewall/metrics, which returns them all in one request and one token.

• GET /firewall/cache/{cacheType}/{ip}

  Get cache ports for a cache type and IP

• POST /firewall/cache/{cacheType}/{ip}

  Add cache ports for a cache type and IP

• DELETE /firewall/cache/{cacheType}/{ip}/ports

  Delete specific cache ports

• DELETE /firewall/cache/{cacheType}/{ip}/all

  Delete all cache ports for a cache type and IP

• DELETE /firewall/cache/{ip}

  Delete all cache data for an IP

Billing

• GET /billing/invoices

  List invoices

  Returns the authenticated user's invoices, newest first, with pagination. Each entry includes billing status, totals, and the parent billable ID.

• POST /billing/invoices/pay

  Pay one or more invoices

  Pays one or more invoices in a single request. Pass a single ID in invoiceIds to pay one invoice, or multiple IDs to bulk-pay. All invoices must belong to the authenticated user and be in a payable status (FINALIZED, PARTIALLY_PAID, UNPAID, or OVERDUE).

  Account credits are applied first; any invoice fully covered by credits is settled without a charge. If a balance remains, gateway and methodId are required, and the remaining invoices are charged — one payment is created per currency group across the paid invoices.

• GET /billing/billables/{id}

  Get a billable (subscription) by ID

  Returns a single subscription owned by the authenticated user, with its services and invoices (newest first) nested. Payment-method and analytics identifiers are omitted. For lightweight order-confirmation polling, use /billing/order-status/{billableId} instead.

• POST /billing/billables/{id}/cancel

  Cancel a subscription

  Cancels a billable subscription. If immediate is true or the billing period has already ended, the subscription is cancelled immediately and associated resources are terminated. Otherwise, the cancellation is scheduled for the end of the current billing period.

• POST /billing/billables/{id}/undo-cancel

  Undo a scheduled cancellation

  Reverses a cancellation that was scheduled for the end of the current billing period, keeping the subscription active. Only works while the subscription is still ACTIVE, has a pending cancellation, and the current billing period has not yet ended.

• POST /billing/billables/{id}/services/{serviceId}/cancel

  Cancel a single service on a subscription

  Cancels one service on a multi-service subscription, leaving the subscription and its remaining services active. If immediate is true the service is dropped from billing at once, its resource is torn down and the subscription's recurring price is recomputed; no refund is issued for the removed service. Otherwise the service is flagged to end at the subscription's current periodEnd and keeps running until then.

  Only available on self-billed subscriptions (gateway INTERNAL, STRIPE or PAYPAL) that have more than one active service. IPV4 services are released by support rather than through this endpoint.

• POST /billing/billables/{id}/services/{serviceId}/undo-cancel

  Undo a scheduled service cancellation

  Clears a service's pending end-of-period cancellation, keeping it on the subscription. Only works while the service has a cancelRequestedAt set, has not already been cancelled, and the subscription's current billing period has not yet ended. A service cancelled immediately cannot be restored this way.

• GET /billing/order-status/{billableId}

  Get order status

  Returns the current status of a billable order, its most recent invoice, and the provisioning status of each resource it covers. Intended for polling an order confirmation page until payment settles and the resources finish provisioning. Only the authenticated user's own billables are accessible.

• GET /stripe/methods

  List saved Stripe payment methods

  Returns the authenticated user's saved Stripe payment methods (card, US bank account/ACH, and SEPA debit) along with their default method. Results are cached per Stripe customer for 10 minutes; the cached flag indicates whether this response was served from cache. Items are raw Stripe PaymentMethod objects, so additional Stripe-provided fields may be present beyond those documented here.

• GET /paypal/methods

  List saved PayPal payment methods

  Returns the authenticated user's vaulted PayPal payment methods along with their default method. The default is only populated when PayPal is the user's default billing gateway; otherwise it is null.

Support

• POST /tickets/upload

  Upload a ticket attachment

  Uploads one file to attach to a ticket or reply. Send one file per request as multipart/form-data under the file field; each file may be at most 95 MB. The returned attachment object is what you pass in the attachments array of POST /tickets or POST /tickets/{ticketId}/reply. Keep the combined size of all attachments on a single ticket or reply under 250 MB.

• POST /tickets

  Open a support ticket

  Opens a new support ticket with message as its first reply. To include files, upload each one with POST /tickets/upload first and pass the returned objects in attachments. Limited to a burst of 10 tickets, refilling at one ticket every 30 seconds.

• POST /tickets/{ticketId}/reply

  Reply to a support ticket

  Adds a reply to one of your tickets. Replying sets the ticket's status back to OPEN, including a ticket that was resolved or closed. Files are attached the same way as when opening a ticket. Limited to a burst of 30 replies across all your tickets (refilling at one every 10 seconds) and 15 replies on any single ticket (refilling at one every 20 seconds).

• GET /tickets/attachments/{attachmentId}

  Get a download link for a ticket attachment

  Returns a signed URL for downloading an attachment on one of your tickets. The URL expires after one hour.

Interactive explorer

Full request and response schemas, with a console for firing authenticated calls. Requires JavaScript.