Platform Reference
Platform Scope
What Gameye is, what it does, and exactly what you can control through the API.
Gameye is a managed container orchestration platform for multiplayer game servers. You call POST /session with a region and a Docker image. Gameye starts the container — on bare metal or cloud, whichever has capacity — and returns an IP address and port within 0.5 seconds. Players connect. You pay per second the session is active. That's the entire model.
Session Lifecycle
Every session passes through three states. Understanding the transition is the foundation of integrating with Gameye correctly.
POST /session response. The container is starting up — it is not yet ready for player connections.DELETE /session/{id}, TTL expiry, or your game server process exiting. Billing ends. Stopped sessions are no longer returned by GET /session. Artifacts can be retrieved before cleanup if configured.API Capabilities
All operations are HTTP. Authentication is a Bearer token in every request header. Two environments exist: sandbox (api.sandbox-gameye.gameye.net) and production (api.gameye.io). The sandbox is identical in API surface — use it for integration testing without production billing.
Authorization: Bearer YOUR_TOKEN_HERE All endpoints require this header. A 401 response means the token is missing, malformed, expired, or lacks permissions for the resource. Contact [email protected] to obtain a token.
POST /session — Create a session
The core operation. Allocates a new game server container in a specified region. Returns connection details within ~0.5 seconds on average.
| Field | Type | Required | Description |
|---|---|---|---|
location | string | Yes | Region to host the session (e.g. europe, us-east). Use GET /available-location/{image} to confirm availability before creating. |
image | string | Yes | Name of the application (Docker image) registered in your Gameye organisation. |
id | string | No | Caller-provided session UUID. If omitted, Gameye generates a UUIDv4. Must be unique — a 409 is returned if the ID already exists. |
version | string | No | Image tag. Defaults to the highest-priority tag configured in your application. |
env | map | No | Environment variables injected into the container at startup. Use for game mode flags, match config, server settings, or secrets. |
args | array | No | Console arguments passed to the container entrypoint. Example: ["--max-players=16", "--map=dust2"] |
labels | map | No | Arbitrary key-value metadata stored with the session. Returned unchanged in GET /session calls. Useful for match IDs, game modes, or internal tracking. |
ttl | integer | No | Maximum session lifetime in seconds. Container is force-terminated and billing stops when TTL expires. Recommended for development environments to prevent runaway costs. |
restart | boolean | No | Auto-restart container on crash. Mutually exclusive with ttl in most configurations. |
id, host (IP address), and ports array — each port object contains type (TCP/UDP), container (internal port), and host (external port).id and let Gameye generate one.GET /available-location and the image name in the Admin Panel.GET /session — List active sessions
Returns all sessions currently active under your API token. Stopped sessions are excluded — once terminated, a session will not appear here.
| Response field | Type | Description |
|---|---|---|
id | string | Session UUID |
image | string | Application name |
tag | string | Image tag running |
location | string | Region the session is hosted in |
host | string | IP address players connect to |
created | number | Unix timestamp (ms) of session creation |
port | map | Port mappings (container port → host port) |
status | string | Current state (Started / Running / Stopped) |
labels | map | Labels set at creation |
playerCount | number | Number of players currently joined |
GET /session/{id} — Describe a session
Returns the same schema as the list endpoint, but for a single session. Use this to poll status after creation, or to retrieve connection details for a known session ID. Returns 404 if the session does not exist or has been stopped.
The players object in the response contains joined (array of player identifiers) and joinedCount (integer). These are populated by the player tracking endpoints below.
DELETE /session/{id} — Terminate a session
Sends SIGTERM to the container and stops billing. Returns 204 No Content on success. Returns 409 if the session is already stopped. Your matchmaker or game backend should call this endpoint when a match ends rather than relying solely on TTL.
POST /session/player/join & /leave — Player tracking
Two endpoints for recording which players are in a session. These are optional but enable accurate playerCount and players.joined data on session queries. Useful for matchmaker backfilling logic — knowing how many slots remain in a running session allows you to add players to an existing match rather than spinning a new one.
GET /available-location/{image} — Check capacity
Returns all locations currently capable of hosting your image, along with IPv4 addresses per location for client-side latency measurement via ICMP ping. Call this before POST /session when you want to route sessions to the lowest-latency region that has capacity.
Do not cache this list. Available locations can change as capacity shifts across providers and regions. Query it fresh per matchmaking cycle when latency routing is required.
GET /logs — Log streaming
Streams stdout/stderr from a running container. Use for real-time debugging during development, or to pipe server logs into your observability stack. Access requires the session ID.
GET /artifact — Artifact retrieval
Downloads files written by the game server process before shutdown — crash dumps, match replays, persistent save data, or any file written to a configured path. Configure artifact paths in the Admin Panel; retrieval is available after the session stops.
GET /tag — Tag verification
Confirms that a specific image tag exists and is available in your organisation before launching a session with it. Use in CI/CD pipelines to gate deployments — verify the tag is present before switching your matchmaker to request it.
Infrastructure Architecture
Gameye maintains dedicated bare metal fleets in each region. Sessions are placed on bare metal by default — predictable, non-oversubscribed performance. When bare metal capacity is reached, the orchestrator automatically bursts onto cloud providers. Your game doesn't know or care which it landed on.
Every region runs across multiple infrastructure providers. If one provider has an issue, sessions are automatically placed on an alternative within the same region. No manual intervention required. This is on by default — there is no configuration needed.
Each container receives guaranteed CPU and RAM as defined in your resource profile. Gameye does not oversubscribe resources — what you configure is what your container gets, regardless of other sessions on the same node. Profiles are set per application in the Admin Panel.
Bridge networking: Gameye auto-assigns an ephemeral external port (32768–60299) and maps it to your container's internal port. No Dockerfile changes needed.
Host networking: A specific host port is reserved and injected as an environment variable (GAMEYE_PORT_TCP_8080, GAMEYE_PORT_UDP_7777). Your server binary reads and binds to it. Requires a custom entrypoint.
Core Objects
| Object | What it is |
|---|---|
| Application | Your game server's Docker image paired with configuration — resource profile, port bindings, registry credentials, and tag priority. Think of it as the template. Sessions are running instances of an application. |
| Session | An active container spawned from an application. Has a unique ID, host IP, port mappings, lifecycle state, labels, and player tracking data. Billing is per second a session is active. |
| Region | A named geographic area (europe, us-east, asia-northeast, etc.) where Gameye maintains infrastructure. Specified at session creation. Gameye load-balances across providers within a region automatically. |
| Location | A specific data centre or cloud zone within a region. Locations handle the actual load-balancing within a region. Exposed via GET /available-location for latency-based routing. |
| Resource Profile | CPU and memory guarantee per container. Set per application. Not oversubscribed — your container gets exactly what is configured. |
| TTL | Maximum session lifetime in seconds. Container is force-terminated at expiry and billing stops. Recommended for dev/test environments. |
| Label | Arbitrary key-value metadata attached at session creation and returned on queries. Stored and returned unchanged — not interpreted by the platform. Use for match IDs, game modes, or any tracking your system needs. |
Matchmaker Integration
Gameye sits downstream of your matchmaker. The matchmaker decides when a match is ready — Gameye receives the POST /session call and returns connection details that the matchmaker forwards to players. The full loop from "match found" to "server ready" takes ~0.5 seconds.
Ships as an official ServerProviderPlugin inside Pragma Engine 2025.2. Configure a Capacity Provider pointing at Gameye — no custom code required. The allocation handoff is handled entirely within Pragma's matchmaking loop.
A Go package (github.com/Gameye/nakama-fleetmanager) provides a Fleet Manager implementation for Nakama 3.21+. Manages the full session lifecycle — creation, player tracking, backfilling, and termination. Five environment variables required: GAMEYE_API_TOKEN, GAMEYE_API_URL, GAMEYE_API_IMAGE, GAMEYE_API_IMAGE_VERSION, GAMEYE_API_REGION.
Idem.gg is a skill-based matchmaker with a dedicated Gameye integration documented at docs.idem.gg/gameye/. Once Idem finds a match, it calls the Gameye Session API to launch a server and returns connection details to players automatically.
FlexMatch sends match events via SNS. Gameye connects via an AWS Lambda that calls POST /session on a MatchmakingSucceeded event and returns connection details through FlexMatch's player notification flow.
PlayFab Matchmaking can trigger session creation via Gameye's HTTP API. Contact the team for the current integration pattern and any helper tooling.
Any system that can make an authenticated HTTP POST request can integrate with Gameye. The Session API is simple enough to call from a game client, a backend Lambda, a dedicated matchmaker service, or a game server itself signalling for a new match.
Onboarding Flow
Gameye provisions sandbox access within 24 hours of request. Onboarding follows five steps.
GAMEYE_PORT_UDP_7777). For bridge, Gameye assigns an ephemeral port automatically.POST /session with your bearer token, image name, and a region. A successful response returns a host IP and port. Direct a game client to those coordinates and you have a running, connected session. You're in production.Billing Model
Billing starts when a session enters the Running state and stops the moment it is terminated — via DELETE /session, TTL expiry, or process exit. Idle capacity is not charged. There is no standing fleet cost.
Data transfer is included in the compute rate. Player traffic, log streaming, and artifact downloads are not billed separately. The number on your pricing page is the whole bill.
Gameye publishes pricing publicly at gameye.com/pricing. You can model costs in a spreadsheet before speaking to anyone. No sales call required to understand what you'll pay.
Set a ttl on sessions in development or test environments to cap the maximum duration of any single session. The container is force-terminated at expiry regardless of state, stopping the billing clock.
Go deeper
Get started
Sandbox access in 24 hours.
Request a token, push your image, call POST /session. Your first live session in under a day.